Previous

Next

JMeter Overview Dashboard - Monitor your load test results in real-time

JMeter Overview Dashboard (Dark Theme) - Monitor your load test results in real-time

Overview

Datadog Backend Listener for Apache JMeter is a JMeter plugin used to send test results to the Datadog platform. It includes the following features:

• Real-time reporting of test metrics (latency, bytes sent and more). See the Metrics section.
• Real-time reporting of test results as Datadog log events.
• Ability to include sub results.

Setup

Installation

The Datadog Backend Listener plugin needs to be installed manually. See the latest release and more up-to-date installation instructions on its GitHub repository.

You can install the plugin either manually or with JMeter Plugins Manager.

No Datadog Agent is necessary.

Manual installation

1. Download the Datadog plugin JAR file from the release page.
2. Place the JAR in the lib/ext directory within your JMeter installation.
3. Launch JMeter (or quit and re-open the application).

JMeter Plugins Manager

1. If not already configured, download the JMeter Plugins Manager JAR.
2. Once you’ve completed the download, place the .jar in the lib/ext directory within your JMeter installation.
3. Launch JMeter (or quit and re-open the application).
4. Go to Options > Plugins Manager > Available Plugins.
5. Search for “Datadog Backend Listener”.
6. Click the checkbox next to the Datadog Backend Listener plugin.
7. Click “Apply Changes and Restart JMeter”.

Configuration

To start reporting metrics to Datadog:

1. Right-click on the thread group or the test plan for which you want to send metrics to Datadog.
2. Go to Add > Listener > Backend Listener.
3. Modify the Backend Listener Implementation and select org.datadog.jmeter.plugins.DatadogBackendClient from the drop-down.
4. Set the apiKey variable to your Datadog API key.
5. Run your test and validate that metrics have appeared in Datadog.

The plugin has the following configuration options:

Statistics Calculation Modes

• ddsketch (default): Uses Datadog’s DDSketch algorithm. It provides approximate percentiles with a 1% error guarantee (relative to the theoretical value) and has a low memory footprint. Note that when comparing with aggregate_report, the difference might be greater because aggregate_report uses the “nearest rank” method, which introduces its own divergence due to quantization (especially with sparse values).
• aggregate_report: Matches JMeter’s “Aggregate Reports” listener. It stores all response times in memory and calculates percentiles using the “nearest rank” method (nearest exact value from the dataset).
• dashboard: Uses a sliding window and interpolation (by default) to calculate percentiles, matching JMeter’s HTML Dashboards. This mode may diverge significantly from the others when the limit of the sliding window is reached (default 20,000, but configurable).

Test Run Tagging

The plugin automatically adds a test_run_id tag to all metrics, logs, and events (Test Started/Ended) to help you isolate and filter specific test executions in Datadog.

• Format: {timestamp}-{hostname}-{random8chars}
  • Example: 2026-01-24T14:30:25Z-myhost-a1b2c3d4
  • In distributed mode, the hostname prefix becomes the runner_id (the JMeter distributed prefix) when present.

You can override this by providing your own test_run_id in the customTags configuration (e.g., test_run_id:my-custom-run-id). Any additional tags you add to customTags will also be included alongside the test_run_id.

Assertion Failures vs Errors

JMeter distinguishes between assertion failures and assertion errors. A failure means the assertion evaluated and did not pass. An error means the assertion could not be evaluated (for example, a null response or a script error). These map to jmeter.assertions.failed and jmeter.assertions.error.

Getting Final Results in Datadog Notebooks

To match JMeter’s Aggregate Reports in a Datadog notebook, set statisticsCalculationMode=aggregate_report and query the jmeter.final_result.* metrics. These are emitted once at test end, so they are ideal for a single, authoritative snapshot.

Note: Since these metrics are emitted only once at the end of the test, ensure your selected time interval includes the test completion time.

Example queries (adjust tags as needed):

avg:jmeter.final_result.response_time.p95{sample_label:total,test_run_id:YOUR_RUN_ID}
avg:jmeter.final_result.responses.error_percent{sample_label:total,test_run_id:YOUR_RUN_ID}
avg:jmeter.final_result.throughput.rps{sample_label:total,test_run_id:YOUR_RUN_ID}

Data Collected

Metrics

The plugin emits three types of metrics:

• Interval metrics (jmeter.*): Real-time metrics reset each reporting interval, useful for monitoring during test execution.
• Cumulative metrics (jmeter.cumulative.*): Aggregate statistics over the entire test duration, similar to JMeter’s Aggregate Reports. These include a final_result tag (true at test end, false during execution).
• Final result metrics (jmeter.final_result.*): Emitted only once at test completion, providing an unambiguous way to query final test results without filtering by tag.

Service Checks

JMeter does not include any service checks.

Events

The plugin sends Datadog Events at the start and end of each test run:

• JMeter Test Started: Sent when the test begins
• JMeter Test Ended: Sent when the test completes

These events appear in the Datadog Event Explorer and can be used to correlate metrics with test execution windows.

Troubleshooting

If you’re not seeing JMeter metrics in Datadog, check your jmeter.log file, which should be in the /bin folder of your JMeter installation.

Troubleshoot missing runner_id tag

This is normal in local mode. The runner_id tag is only emitted in distributed tests, where JMeter provides a distributed prefix. In local runs, use runner_host or runner_mode:local for filtering instead.

Need help? Contact Datadog support.

Further Reading

Additional helpful documentation, links, and articles:

Monitor JMeter test results with DatadogBLOG