Table of Contents

Profiler for Java

The Java agent monitors JVM metrics in-process and collects a heap dump or a thread dump when a configured threshold is exceeded. It targets Java 11+ on a HotSpot JVM.

Publication status. The Java agent lives in the profiler.java repository and is built and tested there. The public Profilers page currently marks the Java agent as coming soon; the Maven coordinates below are the intended release coordinates, not a claim that the artifact is already on Maven Central.

Install

Maven:

<dependency>
  <groupId>com.reignite</groupId>
  <artifactId>profiler</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle:

implementation 'com.reignite:profiler:1.0.0'

Configure

Create profiler.config.json from the configuration block in the portal:

{
  "Performance": {
    "Profiler": {
      "ProfilerID": "your-profiler-id",
      "Environment": "Production",
      "KeyID": "your-key-id",
      "Secret": "your-secret",
      "Disabled": false,
      "StartDelaySecs": 60
    },
    "CollectionOptions": {
      "dumpPath": "./diagnostics/dumps",
      "threadDumpPath": "./diagnostics/threads",
      "maxDumps": 10,
      "maxThreadDumps": 10
    },
    "EventSourceActions": [
      {
        "DisplayName": "heap-memory-used",
        "Operator": ">",
        "Threshold": 500,
        "Dump": true,
        "ThreadDump": true,
        "Cooldown": 300
      },
      {
        "DisplayName": "cpu-load",
        "Operator": ">",
        "Threshold": 80,
        "Dump": false,
        "ThreadDump": true,
        "Cooldown": 180
      }
    ]
  }
}
Section Purpose
Profiler Identity and authentication: ProfilerID, KeyID, Secret, Environment, Disabled, StartDelaySecs.
CollectionOptions Where dumps are written and how many are retained: dumpPath, threadDumpPath, maxDumps, maxThreadDumps.
EventSourceActions The metric thresholds and the collection action each one triggers.

Integrate

import com.reignite.profiler.ReigniteProfiler;

public class MyApplication {
    public static void main(String[] args) throws Exception {
        ReigniteProfiler profiler = new ReigniteProfiler();
        profiler.initialize("profiler.config.json");

        profiler.onDumpCollected(result ->
            System.out.println("Heap dump: " + result.getFilePath()));
        profiler.onThreadDumpCollected(result ->
            System.out.println("Thread dump: " + result.getFilePath()));

        profiler.addShutdownHook();
        profiler.start();

        runApplication();
    }
}

Metrics

The agent monitors these JVM metrics:

Metric Unit
heap-memory-used, heap-memory-committed, heap-memory-max MB
non-heap-memory-used, non-heap-memory-committed MB
thread-count, daemon-thread-count, peak-thread-count threads
cpu-load percent
system-load-average 1-minute load
gc-count, gc-time, gc-count-delta count / ms
uptime ms

Collected artifacts

  • Heap dumps (.hprof) for memory analysis. Open them in Eclipse MAT, VisualVM, IntelliJ IDEA or YourKit.
  • Thread dumps (plain text) for deadlocks and CPU issues. Use fastThread or a text editor.

Best practices

  1. Start with conservative thresholds and adjust from observed behavior.
  2. Use cooldowns of 300–600 seconds to avoid collection storms.
  3. Cap maxDumps and maxThreadDumps so a noisy metric cannot fill the disk.
  4. Use StartDelaySecs to avoid collecting during application startup.
  5. Use thread dumps for deadlocks and CPU issues, heap dumps for memory issues.

Troubleshooting

Symptom Check
No dump is produced The metric never crossed the threshold, or Dump/ThreadDump is false for the action.
Authentication failure ProfilerID, KeyID, Secret or Environment does not match the portal.
Disk pressure Lower maxDumps/maxThreadDumps and increase the cooldown.
JVM refuses the agent Confirm Java 11+ and a HotSpot JVM with diagnostic capabilities.