Prechádzať zdrojové kódy

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.
Rory Hunter 5 rokov pred
rodič
commit
3950c3a9da

+ 45 - 3
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
-<<jvm-options,`jvm.options`>> 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
+<<jvm-options,`jvm.options`>> 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} <<docker,Docker container>> 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
+--------------------------------------------

+ 2 - 1
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 <<heap-size,heap size>>. 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`