Documentation, Enable verbose garbage collection by default on IBM Java/Semeru

[rsherget]

Feature epic details

• For the title of this issue, type: Documentation, Enable verbose garbage collection by default on IBM Java/Semeru
• Link to development epic: Enable verbose garbage collection by default on IBM Java/Semeru open-liberty#23607
• Target GA release: 24003

Operating systems

Does the documentation apply to all operating systems?

• Yes
• No; specify operating systems: ______

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

Verbosegc will be enabled by default on IBM Java and IBM Semeru Runtimes Java. If Liberty is started with the server script, verbosegc will be written to a set of rolling files, unless the JVM has already been configured to send verbosegc to stderr (e.g. containers). This update can be disabled by adding the environment variable VERBOSEGC=false. If a user has already configured some verbosegc, the users configuration will take precedence. Nothing is changed on non-IBM Java/Semeru JVMs (e.g. HotSpot).

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:

Servers are now started with the JVM Option -Xverbosegclog:verbosegc.%seq.log,10,1024. A user can use their own verbosegc jvm option and theirs will take precedence. A user can also add the environment variable VERBOSEGC=false to disable the verbosegc logs.

Updates to existing topics

To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ

https://openliberty.io/docs/latest/log-trace-configuration.html

• Change A server has the following three primary log files: to A server has the following four primary log files:
• In the bullets following the above statement, add another bullet verbosegc.XXX.log - These log files will be created if running on IBM Java and IBM Semeru Runtimes. It contains the verbose garbage collection output from the JVM. It creates up to 10 rolling log files, where the XXX is a number indicating the number of the log file.
• We may want to a new section in this page going a bit more in depth than the brief summary in the above bullet. Possible name for the new section Verbose Garbage Collection Logging. As for the content of the section: By default, if you are using IBM Java, verbose garbage collection logging will be enabled. This will create a set of 10 rolling log files in the logs directory. Verbosegc logging is very useful when encountering Performance issues and OutOfMemory Exceptions, and is generally recommended to have enabled in production due to its low overhead at less than 1%. For more information on verbose garbage collection logs, check out https://www.ibm.com/docs/en/sdk-java-technology/8?topic=gc-verbose-logs. Any verbose garbage collection configuration you have configured will take precedence over this default configuration. This logging can be disabled by adding 'VERBOSEGC=false' in your server.env file.

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.

[ramkumar-k-9286]

Hi Ricky @rsherget

Suggested changes were made to the document.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[rsherget]

The draft changes looks good to me!

[ramkumar-k-9286]

Hi David @dmuelle

Suggested changes were made to the document.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html

Regards,
Ramkumar

CC @dmuelle

[dmuelle]

Peer review

This file contains verbose garbage collection output from the JVM, used specifically with IBM Java and IBM Semeru Runtimes.
--->
This file contains verbose garbage collection output from the JVM and is created only when the Java implementation is either IBM Java and IBM Semeru Runtimes.

Enabled by default in IBM Java, these verbose GC logs are crucial for identifying performance bottlenecks and OutOfMemory errors, with a negligible impact on performance of less than 1%.

So are these logs not enabled by default with Semeru? if not, how do you enable them?

Although default settings apply unless altered, custom configurations can be specified to modify verbose GC behavior.

revise this sentence to use active voice- also it kind of says default settings apply by default, which should go without saying. But it doesn't tell you how to configure the logs, which seems important.

Look for a source about VGC from IBM Semeru instead of IBM Java, if possible. IBM Java only applies to Java 8, while semeru covers 8, 11, 17, 21, and presumably, future releases as well.

[ramkumar-k-9286]

Hi David @dmuelle

Suggested changes were made to the document.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html

Regards,
Ramkumar

[dmuelle]

SInce the default might create multiple files, suggest a slight edit, also for concision and clarity:

This file contains verbose garbage collection output from the JVM and is created only when the Java implementation is either IBM Java and IBM Semeru Runtimes. Verbose garbage collection is enabled by default on IBM Java and IBM Semeru Runtimes. It plays a vital role in diagnosing performance issues and OutOfMemory errors, with minimal impact on performance (less than 1%). Upto 10 rolling logs in the logs directory are supported, where XXX represents the sequence number of the log file. Custom configurations can modify the verbose garbage collection behavior, even though default settings are applied. To disable the verbose garbage collection logs, add VERBOSEGC=false to the server.env file. For more information, see the Verbose garbage collection logs.

------>

These files contain verbose garbage collection output from the JVM and are created by default when the Java implementation is either IBM Java or IBM Semeru Runtimes. Up to 10 rolling log files are created in your log directory, with 1024 GC cycles per file, where XXX represents the sequence number of the log file. Custom configurations take precedence over the this default behavior. To disable the verbose garbage collection logs, add VERBOSEGC=false to the server.env file. For more information, see Verbose garbage collection logs.

[ramkumar-k-9286]

Hi David @dmuelle

Suggested changes were made to the document.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html

Regards,
Ramkumar