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.javarepository 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
- Start with conservative thresholds and adjust from observed behavior.
- Use cooldowns of 300–600 seconds to avoid collection storms.
- Cap
maxDumpsandmaxThreadDumpsso a noisy metric cannot fill the disk. - Use
StartDelaySecsto avoid collecting during application startup. - 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. |