Oracle Cloud Infrastructure Documentation

Configure Thread Snapshots in APM Agent

The thread snapshots feature allows thread stack snapshots collection which can be used for deep dive analysis.

Thread snapshots allows collection of traces like thread stack snapshots, thread memory overhead, thread cpu overhead and gc impact on trace. It collects the thread stack snapshots and stack related data like state and locks, at a specific interval.

Users can enable thread stack snapshots collection for taking stack dump of spans. It provides user code stack visibility.

Thread snapshots collection default time interval is 250 ms.

This feature is disabled by default.

APM Java Agent and APM Tracer support thread snapshots collection. For details about configuring thread snapshots in APM Tracer, see Configure Thread Snapshots in APM Tracer.

This section covers the following:

Prerequisites

  1. Thread Snapshots require JDK8 or higher.

  2. Thread snapshots is supported on APM Java Agent 1.4 version or higher.

Enable Thread Snapshots

After the APM Java Agent has been provisioned, you can enable the thread snapshots feature by updating the AgentConfig.properties file which must be present under the following location:

$DOMAIN_HOME/oracle-apm-agent/config

  • Open the AgentConfig.properties file.
  • Update the following property to true value: 
    com.oracle.apm.agent.deepdive.trace.snapshots.collection.enable=true

    By default, thread snapshots property value is false (Feature disabled).

Configuration Properties

The below table shows the thread snapshots properties than can be configured at runtime.

Property Name Description Unit Default Value Supported Values
com.oracle.apm.agent.deepdive.trace.snapshots.collection.enable Enable or disable deepdive snapshot collection. String false true/false
com.oracle.apm.agent.deepdive.maxPercentTraceExportToCollectorPerMinute Maximum percentage of per minute incoming traces to export them to collector. Percentage 100

Minimum:1

Maximum: 100
com.oracle.apm.agent.deepdive.maxTraceExportToCollectorPerMinute Maximum number of top traces per minute to export them to collector. Number 200

Minimum:1

Maximum: 1500
com.oracle.apm.agent.deepdive.snapshotCollectionIntervalInMS Interval at which thread snapshot data will be collected. Milliseconds 250

Minimum:250

Maximum: 300000
com.oracle.apm.agent.deepdive.maxSnapshotsPerTrace Maximum number of snapshots allowed per trace. Number 16

Minimum: 1

Maximum: 16
com.oracle.apm.agent.deepdive.maxStackTraceDepthPerSnapshot Maximum stack trace frames collected for any thread. Number 256

Minimum: 1

Maximum: 256
com.oracle.apm.agent.deepdive.logLevel Print deep dive logs, which are equal or above to this property value. String INFO

DEBUG, INFO, WARN, SEVERE
com.oracle.apm.agent.deepdive.maxProcessCpuUsagePercent Maximum process CPU usage. It's recommended to maintain overall process CPU usage under this threshold. Number 90

Minimum: 1

Maximum: 90
com.oracle.apm.agent.deepdive.deepDiveCpuUsagePercent.minThreshold Minimum threshold to maintain overall deepdive CPU usage. Percentage 3

Minimum: 1

Maximum: 5
com.oracle.apm.agent.deepdive.deepDiveCpuUsagePercent.maxThreshold Maximum threshold to maintain overall deepdive CPU usage. Percentage 5

Minimum: 5

Maximum: 20
com.oracle.apm.agent.deepdive.traceLifeInMS.minThreshold Minimum threshold for a trace. Milliseconds 50

Minimum: 50

Maximum: 60000
com.oracle.apm.agent.deepdive.traceLifeInMS.maxThreshold Maximum threshold for a trace. Milliseconds 60000

Minimum: 60000

Maximum: 600000

Verify Thread Snapshots

  • To verify that thread snapshots feature has been initialized, check the log file from following location: $DOMAIN_HOME/oracle-apm-agent/deepdive/<server-name>/ApmDeepDiveAgent.log.

    The log file should have look like the following:
     INFO [main] <DeepDiveManager> DeepDiveManger initialized successfully.

  • To verify that thread snapshots feature has been configured properly and data is being uploaded to Application Performance Monitoring, use the Snapshot view option from View Trace or Span Details.