Add docs regarding setting logging levels

This commit clarifies the various ways of setting logging levels and in
what circumstances they are appropriate.

Relates #26344
This commit is contained in:
Jason Tedor 2017-08-23 13:21:44 -04:00 committed by GitHub
parent c1ba860b71
commit bb5b771098

View File

@ -102,6 +102,72 @@ appenders can be found on the
http://logging.apache.org/log4j/2.x/manual/configuration.html[Log4j
documentation].
[float]
[[configuring-logging-levels]]
=== Configuring logging levels
There are four ways to configuring logging levels, each having situations in which they are appropriate to use.
1. Via the command-line: `-E <name of logging hierarchy>=<level>` (e.g.,
`-E logger.org.elasticsearch.transport=trace`). This is most appropriate when
you are temporarily debugging a problem on a single node (for example, a
problem with startup, or during development).
2. Via `elasticsearch.yml`: `<name of logging hierarchy>: <level>` (e.g.,
`logger.org.elasticsearch.transport: trace`). This is most appropriate when
you are temporarily debugging a problem but are not starting Elasticsearch
via the command-line (e.g., via a service) or you want a logging level
adjusted on a more permanent basis.
3. Via <<cluster-logger,cluster settings>>:
+
--
[source,js]
-------------------------------
PUT /_cluster/settings
{
"transient": {
"<name of logging hierarchy>": "<level>"
}
}
-------------------------------
For example:
[source,js]
-------------------------------
PUT /_cluster/settings
{
"transient": {
"logger.org.elasticsearch.transport": "trace"
}
}
-------------------------------
This is most appropriate when you need to dynamically need to adjust a logging
level on an actively-running cluster.
--
4. Via the `log4j2.properties`:
+
--
[source,properties]
--------------------------------------------------
logger.<unique_identifier>.name = <name of logging hierarchy>
logger.<unique_identifier>.level = <level>
--------------------------------------------------
For example:
[source,properties]
--------------------------------------------------
logger.transport.name = org.elasticsearch.transport
logger.transport.level = trace
--------------------------------------------------
This is most appropriate when you need fine-grained control over the logger (for
example, you want to send the logger to another file, or manage the logger
differently; this is a rare use-case).
--
[float]
[[deprecation-logging]]
=== Deprecation logging