From b1be7dcd2d59a1020d5ac1b1c7562c7d6bb41b20 Mon Sep 17 00:00:00 2001 From: Rory Hunter Date: Fri, 28 Feb 2020 21:26:53 +0000 Subject: [PATCH] Document how to change GC logging behaviour (#52879) Closes #43990. Describe how to change the default GC settings without changing the default `jvm.options`. Give examples using `jvm.options.d`, and `ES_JAVA_OPTS` with Docker. --- .../important-settings/gc-logging.asciidoc | 48 +++++++++++++++++-- docs/reference/setup/jvm-options.asciidoc | 3 +- 2 files changed, 47 insertions(+), 4 deletions(-) diff --git a/docs/reference/setup/important-settings/gc-logging.asciidoc b/docs/reference/setup/important-settings/gc-logging.asciidoc index 30df94d071f..5d5f3ac589a 100644 --- a/docs/reference/setup/important-settings/gc-logging.asciidoc +++ b/docs/reference/setup/important-settings/gc-logging.asciidoc @@ -1,7 +1,49 @@ [[gc-logging]] === GC logging -By default, Elasticsearch enables GC logs. These are configured in -<> and default to the same default location as the -Elasticsearch logs. The default configuration rotates the logs every 64 MB and +By default, {es} enables GC logs. These are configured in +<> and output to the same default location as +the {es} logs. The default configuration rotates the logs every 64 MB and can consume up to 2 GB of disk space. + +You can reconfigure JVM logging using the command line options described in +https://openjdk.java.net/jeps/158[JEP 158: Unified JVM Logging]. Unless you +change the default `jvm.options` file directly, the {es} default +configuration is applied in addition to your own settings. To disable the +default configuration, first disable logging by supplying the +`-Xlog:disable` option, then supply your own command line options. This +disables __all__ JVM logging, so be sure to review the available options +and enable everything that you require. + +To see further options not contained in the original JEP, see +https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html#enable-logging-with-the-jvm-unified-logging-framework[Enable +Logging with the JVM Unified Logging Framework]. + +==== Examples + +* Change the default GC log output location to `/opt/my-app/gc.log` by + creating `$ES_HOME/config/jvm.options.d/gc.options` with some sample + options: ++ +[source,shell] +-------------------------------------------- +# Turn off all previous logging configuratons +-Xlog:disable + +# Default settings from JEP 158, but with `utctime` instead of `uptime` to match the next line +-Xlog:all=warning:stderr:utctime,level,tags + +# Enable GC logging to a custom location with a variety of options +-Xlog:gc*,gc+age=trace,safepoint:file=/opt/my-app/gc.log:utctime,pid,tags:filecount=32,filesize=64m +-------------------------------------------- + +* Configure an {es} <> to send GC debug logs to + standard error (`stderr`). This lets the container orchestrator + handle the output. If using the `ES_JAVA_OPTS` environment variable, + specify: ++ +[source,sh] +-------------------------------------------- +MY_OPTS="-Xlog:disable -Xlog:all=warning:stderr:utctime,level,tags -Xlog:gc=debug:stderr:utctime" +docker run -e ES_JAVA_OPTS="$MY_OPTS" # etc +-------------------------------------------- diff --git a/docs/reference/setup/jvm-options.asciidoc b/docs/reference/setup/jvm-options.asciidoc index 3a619355eda..053b9cc8df8 100644 --- a/docs/reference/setup/jvm-options.asciidoc +++ b/docs/reference/setup/jvm-options.asciidoc @@ -3,7 +3,8 @@ You should rarely need to change Java Virtual Machine (JVM) options. If you do, the most likely change is setting the <>. The remainder of -this document explains in detail how to set JVM options. +this document explains in detail how to set JVM options. You can set options +either with `jvm.options` files or with the `ES_JAVA_OPTS` environment variable. The preferred method of setting or overriding JVM options is via JVM options files. When installing from the tar or zip distributions, the root `jvm.options`