Browse Source

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
Jason Tedor 8 years ago
parent
commit
bb5b771098
1 changed files with 66 additions and 0 deletions
  1. 66 0
      docs/reference/setup/logging-config.asciidoc

+ 66 - 0
docs/reference/setup/logging-config.asciidoc

@@ -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