# Pristine Capture: How yc-360 Script Intelligently Collects artifacts

The yc-360 Script intelligently captures key artifacts when performance issues start brewing in an application. These artifacts include garbage collection logs, thread dumps, heap dumps, netstat, vmstat, iostat, disk usage, and more.

Among these, the following three are the most critical:

  • Garbage collection log
  • Thread dump
  • Heap Dump

The yc-360 script makes rigorous attempts to ensure these critical artifacts are captured accurately. This document outlines the step-by-step process the script follows to collect each of these artifacts.

# Garbage collection log

The yc-360 script attempts to collect the garbage collection (GC) log using the following methods, in order of precedence:

# Attempt 1: -Xloggc:< file-path >

For Java 8 and earlier, the GC log file is specified using the -Xloggc:<file-path> JVM argument. The script checks whether this argument is configured and, if so, captures the GC log from the specified file path.

# Attempt 2: -Xlog:gc*:file=< file-path >

Starting with Java 9, the GC log configuration uses -Xlog:gc*:file=<file-path> JVM argument. The script checks for this setting and captures the log from the defined path.

# Attempt 3: gcPath argument

You can manually specify the GC log file path using the gcPath argument. When this is set, the script skips the automatic detection steps and reads the log from the path you provide.

Use Case: If you're already using a custom script to collect GC logs, this option allows you to pass the log file location to the yc-360 script.

Example:

-gcPath /opt/server1/myGCLog.gc
1

# Attempt 4: gcCaptureCmd argument

You can provide a custom script or command using the gcCaptureCmd argument. The yc-360 script will execute this command and the command should return the file path of the GC log. The yc-360 script will read the GC log from the returned file path.

Example:

-gcCaptureCmd /opt/server1/capture-gc.sh
1

INFO

To this gcCaptureCmd an implicit variable $pid is available, which represents the process Id of the application that is currently monitored. You can use this $pid in the command to retrieve the gc log file path.

# Attempt 5: jstat

If the above options fail, the script falls back to using the jstat tool (opens new window) from the JDK to gather GC statistics.

# Attempt 6: jattach

As a last resort, the script uses the open-source 'jattach' library (opens new window) to capture the GC logs.

# Thread dump

The yc-360 script collects thread dumps using the following sequence of methods:

# Attempt 1: jstack

The primary method uses the standard jstack tool (opens new window) included in the JDK.

# Attempt 2: jattach

If jstack fails, the script uses the open source 'jattach' library (opens new window) to collect the thread dump.

# Attempt 3: tdPath argument

You can provide a path to a pre-captured thread dump using the tdPath argument. When specified, the script reads the thread dump from this location instead of capturing it.

Use Case: If you're already using a custom script to collect thread dumps, this option allows you to pass the thread dump file location to the yc-360 script.

Example:

-tdPath /opt/server1/myThreaddumps.txt
1

# Attempt 4: tdCaptureCmd argument

You can provide a custom script or command using the tdCaptureCmd argument. The yc-360 script will execute this command and the command should return the file path of the thread dump. The yc-360 script will read the thread dump from the returned file path.

Example:

-tdCaptureCmd /opt/server1/capture-td.sh
1

INFO

To this tdCaptureCmd an implicit variable $pid is available, which represents the process Id of the application that is currently monitored. You can use this $pid in the command to retrieve the thread dump file path.

# Attempt 5: jstack -F

If the application is severely unresponsive, the yc-360 script uses jstack -F (force option) to attempt capturing the thread dump. This approach may produce partial data, missing thread states, lock IDs, etc., but it's better than having no data.

# Attempt 6: jhsdb jstack

As a fallback, especially for JDK 11 and later where jstack -F is deprecated, the yc-360 script uses jhsdb jstack (opens new window) to collect the thread dump. This tool connects to a running Java process for troubleshooting.

# Heap dump

Capturing a heap dump is an intrusive operation and can pause the application for seconds or even minutes depending on the memory size. Thus, yc-360 script does not collect a heap dump by default.

To enable heap dump collection, you must explicitly pass the hd argument to the script.

Once enabled, the script uses the following methods:

# Attempt 1: jcmd Tool

The primary method is the standard jcmd tool (opens new window) available in the JDK.

# Attempt 2: jattach Tool

If jcmd fails, the script falls back to using the open source jattach library (opens new window) to generate the heap dump.

# Attempt 3: hdPath argument

You can provide a path to a pre-captured heap dump using the hdPath argument. When specified, the script reads the heap dump from this location instead of capturing it.

Use Case: If you're already using a custom script to collect heap dumps, this option allows you to pass the heap dump file location to the yc-360 script.

Example:

-hdPath /opt/server1/myHeapDump.txt
1

# Attempt 4: hdCaptureCmd argument

You can provide a custom script or command using the hdCaptureCmd argument. The yc-360 script will execute this command and the command should return the file path of the heap dump. The yc-360 script will read the heap dump from the returned file path.

Example:

-hdCaptureCmd /opt/server1/capture-hd.sh
1

INFO

To this hdCaptureCmd an implicit variable $pid is available, which represents the process Id of the application that is currently monitored. You can use this $pid in the command to retrieve the thread dump file path.

← Custom Capture →