From f1587dcad0ada74f1b189d69feb5e60884a6d288 Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 22 Jul 2024 07:29:26 +0100 Subject: [PATCH 1/2] Rework docs on logging levels Clarify that the default config is the recommended one, and that users should not normally enable `DEBUG` or `TRACE` logging without looking at the source code. Also reorders the information a bit for easier reading. --- docs/reference/setup/logging-config.asciidoc | 52 ++++++++++++++------ 1 file changed, 37 insertions(+), 15 deletions(-) diff --git a/docs/reference/setup/logging-config.asciidoc b/docs/reference/setup/logging-config.asciidoc index 7b36b6382c9bf..b86f39380354d 100644 --- a/docs/reference/setup/logging-config.asciidoc +++ b/docs/reference/setup/logging-config.asciidoc @@ -140,19 +140,33 @@ documentation]. [[configuring-logging-levels]] === Configuring logging levels -Each Java package in the {es-repo}[{es} source code] has a related logger. For -example, the `org.elasticsearch.discovery` package has -`logger.org.elasticsearch.discovery` for logs related to the -<> process. - -To get more or less verbose logs, use the <> to change the related logger's log level. Each logger -accepts Log4j 2's built-in log levels, from least to most verbose: `OFF`, -`FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`. The default log level is -`INFO`. Messages logged at higher verbosity levels (`DEBUG` and `TRACE`) are -only intended for expert use. To prevent leaking sensitive information in logs, -{es} will reject setting certain loggers to higher verbosity levels unless -<> is enabled. +Log4J 2 log messages include a _level_ field. In order of increasing verbosity, +the available levels are `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG` or `TRACE`. +By default {es} includes all messages at levels `INFO`, `WARN`, `ERROR` and +`FATAL` in its logs, but filters out messages at levels `DEBUG` and `TRACE`. +This is the recommended configuration. Do not filter out messages at `INFO` or +higher log levels or else you may not be able to understand your cluster's +behaviour or troubleshoot common problems. Do not enable logging at levels +`DEBUG` or `TRACE` unless you are following instructions elsewhere in this +manual which call for more detailed logging, or you are an expert user who will +be reading the {es} source code to determine the meaning of the logs. + +Messages are logged by a hierarchy of loggers which matches the hierarchy of +Java packages and classes in the {es-repo}[{es} source code]. Every logger has +a corresponding <> which can be used +to control the verbosity of its logs. The setting's name is the fully-qualified +name of the package or class, prefixed with `logger.`. For example, the +`org.elasticsearch.discovery` package contains functionality related to the +<> process, and you can control the +verbosity of its logs with the `logger.org.elasticsearch.discovery` dynamic +setting. You may set each logger's setting to the name of a log level, for +instance `DEBUG`, which means that messages from this logger at levels up to +the specified one will be included in the logs. Each logger can also be set to +`OFF` to suppress its messages entirely. + +For example, to enable `DEBUG` logging for the `org.elasticsearch.discovery` +package, use the <> as +follows: [source,console] ---- @@ -164,8 +178,8 @@ PUT /_cluster/settings } ---- -To reset a logger's verbosity to its default level, set the logger setting to -`null`: +To reset this package's log verbosity to its default level, set the logger +setting to `null`: [source,console] ---- @@ -211,6 +225,14 @@ formatting the same information in different ways, renaming the logger or adjusting the log level for specific messages. Do not rely on the contents of the application logs remaining precisely the same between versions. +NOTE: To prevent leaking sensitive information in logs, {es} suppresses certain +log messages by default even at the highest verbosity levels. To disable this +protection on a node, set the Java system property +`es.insecure_network_trace_enabled` to `true`. This feature is primarily +intended for test systems which do not contain any sensitive information. If you +set this property on a system which contains sensitive information, you must +protect your logs from unauthorized access. + [discrete] [[deprecation-logging]] === Deprecation logging From 7d5a97f0d113beea90a603fb7a6dab0d8b537f57 Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 22 Jul 2024 11:00:16 +0100 Subject: [PATCH 2/2] Review suggestions --- docs/reference/setup/logging-config.asciidoc | 36 ++++++++++++-------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/reference/setup/logging-config.asciidoc b/docs/reference/setup/logging-config.asciidoc index b86f39380354d..e382bbdacb464 100644 --- a/docs/reference/setup/logging-config.asciidoc +++ b/docs/reference/setup/logging-config.asciidoc @@ -140,8 +140,16 @@ documentation]. [[configuring-logging-levels]] === Configuring logging levels -Log4J 2 log messages include a _level_ field. In order of increasing verbosity, -the available levels are `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG` or `TRACE`. +Log4J 2 log messages include a _level_ field, which is one of the following (in +order of increasing verbosity): + +* `FATAL` +* `ERROR` +* `WARN` +* `INFO` +* `DEBUG` +* `TRACE` + By default {es} includes all messages at levels `INFO`, `WARN`, `ERROR` and `FATAL` in its logs, but filters out messages at levels `DEBUG` and `TRACE`. This is the recommended configuration. Do not filter out messages at `INFO` or @@ -155,18 +163,18 @@ Messages are logged by a hierarchy of loggers which matches the hierarchy of Java packages and classes in the {es-repo}[{es} source code]. Every logger has a corresponding <> which can be used to control the verbosity of its logs. The setting's name is the fully-qualified -name of the package or class, prefixed with `logger.`. For example, the -`org.elasticsearch.discovery` package contains functionality related to the -<> process, and you can control the -verbosity of its logs with the `logger.org.elasticsearch.discovery` dynamic -setting. You may set each logger's setting to the name of a log level, for -instance `DEBUG`, which means that messages from this logger at levels up to -the specified one will be included in the logs. Each logger can also be set to -`OFF` to suppress its messages entirely. - -For example, to enable `DEBUG` logging for the `org.elasticsearch.discovery` -package, use the <> as -follows: +name of the package or class, prefixed with `logger.`. + +You may set each logger's verbosity to the name of a log level, for instance +`DEBUG`, which means that messages from this logger at levels up to the +specified one will be included in the logs. You may also use the value `OFF` to +suppress all messages from the logger. + +For example, the `org.elasticsearch.discovery` package contains functionality +related to the <> process, and you can +control the verbosity of its logs with the `logger.org.elasticsearch.discovery` +setting. To enable `DEBUG` logging for this package, use the +<> as follows: [source,console] ----