From c220086967e212309be324963028e02dc3127a65 Mon Sep 17 00:00:00 2001 From: Luke Elmers Date: Thu, 15 Apr 2021 14:53:01 -0600 Subject: [PATCH] Add warnings about default appender removal to the docs. --- .../logging-configuration-migration.asciidoc | 18 +++++++++++++----- docs/settings/logging-settings.asciidoc | 16 ++++++++++++---- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/docs/developer/architecture/core/logging-configuration-migration.asciidoc b/docs/developer/architecture/core/logging-configuration-migration.asciidoc index 19f10a881d5e8..5d8a1689ee0f0 100644 --- a/docs/developer/architecture/core/logging-configuration-migration.asciidoc +++ b/docs/developer/architecture/core/logging-configuration-migration.asciidoc @@ -3,11 +3,19 @@ Compatibility with the legacy logging system is assured until the end of the `v7` version. All log messages handled by `root` context are forwarded to the legacy logging service. If you re-write -root appenders, make sure that it contains `default` appender to provide backward compatibility. - -NOTE: When you switch to the new logging configuration, you will start seeing duplicate log entries in both formats. -These will be removed when the `default` appender is no longer required. If you define an appender for a logger, -the log messages aren't handled by the `root` logger anymore and are not forwarded to the legacy logging service. +root appenders, make sure that it contains `default` appender if you wish +to provide backward compatibility with `v7`. + +WARNING: When you switch to the new logging configuration, you will start seeing duplicate log entries in both formats +if you still have the `default` appender set in the `root` context. +Removing the `default` will get rid of the duplicate entries, however, +it means you will no longer be receiving logs in the legacy format. +This may break your existing integrations if you are ingesting the Kibana +logs somewhere and relying on the legacy format. In particular, if you use +the https://www.elastic.co/guide/en/beats/filebeat/7.x/filebeat-module-kibana.html[Filebeat Kibana module] +to ingest your Kibana logs, it is recommended that you do *not* remove +the `default` appender before `v8`, as logs will no longer be indexed +with the same fields. [[logging-pattern-format-old-and-new-example]] [options="header"] diff --git a/docs/settings/logging-settings.asciidoc b/docs/settings/logging-settings.asciidoc index aa38d54305eec..af32422471b7c 100644 --- a/docs/settings/logging-settings.asciidoc +++ b/docs/settings/logging-settings.asciidoc @@ -5,12 +5,20 @@ ++++ Compatibility with the legacy logging system is assured until the end of the `v7` version. -All log messages handled by `root` context (default) are forwarded to the legacy logging service. +All log messages handled by the `root` context's `default` appender are forwarded to the legacy logging service. The logging configuration is validated against the predefined schema and if there are any issues with it, {kib} will fail to start with the detailed error message. -NOTE: When you switch to the new logging configuration, you will start seeing duplicate log entries in both formats. -These will be removed when the `default` appender is no longer required. +WARNING: When you switch to the new logging configuration, you will start seeing duplicate log entries in both formats +if you still have the `default` appender set in the `root` context. +Removing the `default` will get rid of the duplicate entries, however, +it means you will no longer be receiving logs in the legacy format. +This may break your existing integrations if you are ingesting the Kibana +logs somewhere and relying on the legacy format. In particular, if you use +the https://www.elastic.co/guide/en/beats/filebeat/7.x/filebeat-module-kibana.html[Filebeat Kibana module] +to ingest your Kibana logs, it is recommended that you do *not* remove +the `default` appender before `v8`, as logs will no longer be indexed +with the same fields. Here are some configuration examples for the most common logging use cases: @@ -36,7 +44,7 @@ logging: ==== Log in json format Log the default log format to json layout instead of pattern (the default). -With `json` layout log messages will be formatted as JSON strings in https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[ECS format] that includes a timestamp, log level, logger, message text and any other metadata that may be associated with the log message itself +With `json` layout log messages will be formatted as JSON strings in https://www.elastic.co/guide/en/ecs/1.9/ecs-reference.html[ECS format] that includes a timestamp, log level, logger, message text and any other metadata that may be associated with the log message itself [source,yaml] ----