Java Flight Recorder (JFR) is a tool for helping debug many kinds of performance issues.  JFR captures a large set of JVM performance information into a flight recording file.  The recording can then be analyzed offline using Java Mission Control.

As of Contrast Java Agent version 6.28.0, the agent can generate JFR captures. If you are using a version newer than 6.28.0 this will be the easiest way to proceed.

# Record to file "recording.jfr", use the settings "profile"
-XX:StartFlightRecording=filename=recording.jfr,dumponexit=true,settings=profile

# Record to file "recording.jfr", record for 5mins before dumping results, use the settings "profile"
-XX:StartFlightRecording=filename=recording.jfr,duration=300s,dumponexit=true,settings=profile

# Record to file "recording.jfr", delay starting recording for 30s, use the settings "profile"
-XX:StartFlightRecording=filename=recording.jfr,delay=30s,dumponexit=true,settings=profile

-XX:StartFlightRecording=disk=true,name=recording-1,filename=/tmp/agent.jfr,maxage=15m,dumponexit=true,settings=profile

Requirements

Java agent version 6.28.0 or newer.

A version of the JVM that supports JFR. Therefore excluded are:

• Early versions of Java 8

• IBM OpenJ9 JVMs

On unsupported JVMs this config is a noop.

Quick Start

The simplest way to enable automatic JFR recording is to set the contrast.agent.java.jfr_recording property to start:

-Dcontrast.agent.java.jfr_recording=start

This starts recording immediately with all defaults applied. No other configuration is required.

Without setting anything, automatic recording is disabled by default as per before.

How It Works

When enabled, the agent starts a JFR recording and periodically dumps incremental .jfr files to disk. Each dump file contains only the events from its recording interval — files do not overlap. On JVM shutdown, a final dump is written automatically.

Dump files are named: <name>-<6-digit-id>-<yyyyMMdd-HHmmss-SSS>.jfr

For example: contrast-agent-482917-20260304-143022-847.jfr

The 6-digit ID is randomly generated per agent session to prevent filename collisions when multiple agents write to the same directory.

Configuration

The property accepts a comma-separated list of key=value pairs. All keys are optional — any omitted key uses its default.

-Dcontrast.agent.java.jfr_recording=dir=/var/log/contrast,dump_interval=5m,disk_limit=1g

Duration values

Durations support the suffixes ms, s, m, h. A bare number is treated as seconds.

Examples: 500ms, 30s, 10m, 2h, 60

Size values

Sizes support the suffixes k/kb, m/mb, g/gb (case-insensitive). A bare number is treated as bytes.

Examples: 512k, 256m, 256mb, 2g, 2gb, 1073741824

Size Limits

There are two independent size controls:

maxsize — In-memory buffer limit (default: 256 MB)

This controls how much event data JFR keeps in its circular in-memory buffer. When the buffer fills up, the oldest events are evicted. This directly affects the maximum size of each individual dump file. Increasing this value retains more event history per dump but uses more heap memory.

disk_limit — Total disk budget (default: 2 GB)

This controls the total size of all contrast-*.jfr files in the output directory. After each dump, the agent checks whether the total size of agent-created JFR files exceeds the limit. If it does, the oldest files are deleted until the total is back within budget. Files not created by the agent (those not matching the contrast-*.jfr pattern) are ignored.

Setting disk_limit=0 disables disk limit enforcement entirely (unlimited).

How they interact: maxsize controls how large each individual dump can be. disk_limit controls how many dumps are retained on disk. For example, with maxsize=256m and disk_limit=2g, the agent retains roughly 8 dump files before the oldest ones are cleaned up.

Delayed Start and Fixed-Duration Recording

delay_start

Delays the start of the recording by the specified duration. This is useful when you want to skip the application startup phase and only capture steady-state behaviour.

-Dcontrast.agent.java.jfr_recording=delay_start=5m

If the JVM shuts down before the delay elapses, no recording is produced and a warning is logged.

record_for

Records for a fixed duration, then performs a final dump and stops. No further recordings are taken, and the shutdown hook does not produce an additional dump.

-Dcontrast.agent.java.jfr_recording=record_for=1h

The timer starts from when the recording actually begins (after any delay_start), not from agent startup.

Combining both

-Dcontrast.agent.java.jfr_recording=delay_start=5m,record_for=30m

This skips the first 5 minutes, then records for 30 minutes, then stops.

Examples

Minimal — start with all defaults:

-Dcontrast.agent.java.jfr_recording=start

Custom output directory and faster dumps:

-Dcontrast.agent.java.jfr_recording=dir=/var/log/jfr,dump_interval=1m

Limited disk usage:

-Dcontrast.agent.java.jfr_recording=disk_limit=500m

Capture a 30-minute window after warmup:

-Dcontrast.agent.java.jfr_recording=delay_start=10m,record_for=30m,dir=/tmp/jfr-capture

Unlimited disk, larger buffer, detailed settings:

-Dcontrast.agent.java.jfr_recording=disk_limit=0,maxsize=512m,settings=profile,dump_interval=5m

Log Messages

A log message will be logged on startup when the config is detected

2026-03-06 10:42:07,517 [main JfrRecordingManagerImpl] INFO - JFR auto-capture enabled: id=872490, name=contrast-agent, settings=profile, dir=/Users/jmccartney/tmp/2026/2026-q1/misc/jfr, dump_interval=PT1M, disk_limit=157286400 bytes, maxsize=268435456 bytes, maxage=null, gzip=true

After each file is written a message will be recorded

2026-03-06 11:36:07,647 [Contrast IO Executor JfrRecordingManagerImpl] INFO - JFR recording dumped to /Users/contrast/tmp/2026/2026-q1/misc/jfr/contrast-agent-872490-20260306-113607-540.jfr

See also:

• Java Agent Effects on Application Performance (Assess)
• Java Agent Effects on Startup Performance
• Red Hat Customer Portal - Using JDK Flight Recorder with OpenJDK