Skip to content

Commit

Permalink
Add warnings about default appender removal to the docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
lukeelmers committed Apr 15, 2021
1 parent 6e98962 commit c220086
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 9 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
16 changes: 12 additions & 4 deletions docs/settings/logging-settings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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]
----
Expand Down

0 comments on commit c220086

Please sign in to comment.