You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[Added] Add cumulative metrics support to mirror JMeter's Aggregate Report.
6
+
*[Added] Add `statisticsCalculationMode` configuration option to control percentile calculation algorithms (`ddsketch`, `aggregate_report`, `dashboard`).
7
+
*[Added] Add assertion metrics to track success and failure of assertions.
8
+
*[Added] Add Datadog Events for test start and test end.
5
9
6
-
***Added***:
10
+
## 0.5.0
7
11
8
-
* Initial release.
12
+
*[Added] Add ability to exclude sample results to be sent as logs based on response code regex
13
+
See [#47](https://github.com/DataDog/jmeter-datadog-backend-listener/issues/47)
14
+
15
+
## 0.4.0
16
+
17
+
*[Changed] Set configured tags on plugin generated logs. (See [#45](https://github.com/DataDog/jmeter-datadog-backend-listener/pull/45)).
18
+
19
+
## 0.3.1
20
+
21
+
*[Fixed] Setting `includeSubresults` to `true` will now also include the parent results as well as subresults recursively (See [#35](https://github.com/DataDog/jmeter-datadog-backend-listener/pull/35)).
22
+
23
+
## 0.3.0
24
+
25
+
*[Added] Add ability to release to Maven Central. See [#26](https://github.com/DataDog/jmeter-datadog-backend-listener/pull/26)
26
+
*[Added] Add custom tags to global metrics. See [#23](https://github.com/DataDog/jmeter-datadog-backend-listener/pull/23)
27
+
28
+
## 0.2.0
29
+
30
+
*[Added] Add `customTags` config option. See [#15](https://github.com/DataDog/jmeter-datadog-backend-listener/pull/15)
31
+
*[Added] Tag metrics by `thread_group`. See [#17](https://github.com/DataDog/jmeter-datadog-backend-listener/pull/17)
32
+
*[Added] Add `thread_group` to log payload. See [#18](https://github.com/DataDog/jmeter-datadog-backend-listener/pull/18)
Datadog Backend Listener for Apache JMeter is an open source JMeter plugin used to send test results to the Datadog platform. It provides real-time reporting of test metrics like latency, the number of bytes sent and received, and more. You can also send to Datadog complete test results as log entries.
7
+
Datadog Backend Listener for Apache JMeter is a JMeter plugin used to send test results to the Datadog platform. It includes the following features:
8
+
9
+
- Real time reporting of test metrics (latency, bytes sent and more). See the Metrics section.
10
+
- Real time reporting of test results as Datadog log events.
11
+
- Ability to include sub results.
6
12
7
13
## Setup
8
14
9
15
### Installation
10
16
11
17
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][1].
12
18
19
+
You can install the plugin either manually or with JMeter Plugins Manager.
20
+
21
+
No Datadog Agent is necessary.
22
+
13
23
#### Manual installation
14
24
15
-
1. Download the Datadog plugin JAR file from the [release page][5]
25
+
1. Download the Datadog plugin JAR file from the [release page][5].
16
26
2. Place the JAR in the `lib/ext` directory within your JMeter installation.
17
27
3. Launch JMeter (or quit and re-open the application).
18
28
19
29
#### JMeter plugins Manager
20
30
21
31
1. If not already configured, download the [JMeter Plugins Manager JAR][6].
22
-
2. Once you've completed the download, place the `.jar` in the `lib/ext` directory within your JMeter installation.
23
-
3. Launch JMeter (or quit and re-open the application).
24
-
4. Go to `Options > Plugins Manager > Available Plugins`.
32
+
2. Once you've completed the download, place the `.jar` in the `lib/ext` directory within your JMeter installation.
33
+
3. Launch JMeter (or quit and re-open the application).
34
+
4. Go to `Options > Plugins Manager > Available Plugins`.
25
35
5. Search for "Datadog Backend Listener".
26
36
6. Click the checbox next to the Datadog Backend Listener plugin.
27
37
7. Click "Apply Changes and Restart JMeter".
@@ -30,9 +40,9 @@ The Datadog Backend Listener plugin needs to be installed manually. See the late
30
40
31
41
To start reporting metrics to Datadog:
32
42
33
-
1. Right click on the thread group or the test plan for which you want to send metrics to Datadog.
43
+
1. Right click on the thread group or the test plan for which you want to send metrics to Datadog.
34
44
2. Go to `Add > Listener > Backend Listener`.
35
-
3. Modify the `Backend Listener Implementation` and select `org.datadog.jmeter.plugins.DatadogBackendClient` from the drop-down.
45
+
3. Modify the `Backend Listener Implementation` and select `org.datadog.jmeter.plugins.DatadogBackendClient` from the drop-down.
36
46
4. Set the `apiKey` variable to [your Datadog API key][7].
37
47
5. Run your test and validate that metrics have appeared in Datadog.
38
48
@@ -42,38 +52,88 @@ The plugin has the following configuration options:
|datadogUrl | false |https://api.datadoghq.com/api/| You can configure a different endpoint, for instance https://api.datadoghq.eu/api/ if your datadog instance is in the EU|
45
-
|logIntakeUrl | false |https://http-intake.logs.datadoghq.com/v1/input/| You can configure a different endpoint, for instance https://http-intake.logs.datadoghq.eu/v1/input/ if your datadog instance is in the EU.|
46
-
|metricsMaxBatchSize|false|200|Metrics are submitted every 10 seconds in batches of size `metricsMaxBatchSize`.|
55
+
|logIntakeUrl | false |https://http-intake.logs.datadoghq.com/v1/input/| You can configure a different endpoint, for instance https://http-intake.logs.datadoghq.eu/v1/input/ if your datadog instance is in the EU|
56
+
|metricsMaxBatchSize|false|200|Metrics are submitted every 10 seconds in batches of size `metricsMaxBatchSize`|
47
57
|logsBatchSize|false|500|Logs are submitted in batches of size `logsBatchSize` as soon as this size is reached.|
48
-
|sendResultsAsLogs|false|false|By default only metrics are reported to Datadog. To report individual test results as log events, set this field to `true`.|
58
+
|sendResultsAsLogs|false|true|By default, individual test results are reported as log events. Set to `false` to disable log reporting.|
49
59
|includeSubresults|false|false|A subresult is for instance when an individual HTTP request has to follow redirects. By default subresults are ignored.|
50
60
|excludeLogsResponseCodeRegex|false|`""`| Setting `sendResultsAsLogs` will submit all results as logs to Datadog by default. This option lets you exclude results whose response code matches a given regex. For example, you may set this option to `[123][0-5][0-9]` to only submit errors.|
51
-
|samplersRegex|false|.*|An optional regex to filter the samplers to monitor.|
52
-
|customTags|false|`""`|Comma-separated list of tags to add to every metric
61
+
|samplersRegex|false|`""`|Regex to filter which samplers to include. By default all samplers are included.|
62
+
|customTags|false|`""`|Comma-separated list of tags to add to every metric.|
63
+
|statisticsCalculationMode|false|`ddsketch`|Algorithm for percentile calculation: `ddsketch` (default), `aggregate_report` (matches JMeter Aggregate Reports), or `dashboard` (matches JMeter HTML Dashboards).|
64
+
65
+
#### Statistics Calculation Modes
66
+
67
+
-**ddsketch** (default): Uses Datadog's [DDSketch algorithm][8]. 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).
68
+
-**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).
69
+
-**dashboard**: Uses a sliding window and interpolation (by default) to calculate percentiles, matching [JMeter's HTML Dashboards][9]. This mode may diverge significantly from the others when the limit of the sliding window is reached (default 20,000, but [configurable][10]).
70
+
71
+
#### Test Run Tagging
72
+
73
+
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.
- In distributed mode, the `hostname` prefix becomes the `runner_id` (the JMeter distributed prefix) when present.
78
+
79
+
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`.
80
+
81
+
#### Assertion Failures vs Errors
82
+
83
+
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`.
84
+
85
+
#### Getting Final Results in Datadog Notebooks
86
+
87
+
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.
88
+
89
+
**Note**: Since these metrics are emitted only once at the end of the test, ensure your selected time interval includes the test completion time.
See [metadata.csv][2] for a list of metrics provided by this check.
59
104
105
+
The plugin emits three types of metrics:
106
+
-**Interval metrics** (`jmeter.*`): Real-time metrics reset each reporting interval, useful for monitoring during test execution.
107
+
-**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).
108
+
-**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.
109
+
60
110
### Service Checks
61
111
62
112
JMeter does not include any service checks.
63
113
64
114
### Events
65
115
66
-
JMeter does not include any events.
116
+
The plugin sends Datadog Events at the start and end of each test run:
117
+
-**JMeter Test Started**: Sent when the test begins
118
+
-**JMeter Test Ended**: Sent when the test completes
119
+
120
+
These events appear in the Datadog Event Explorer and can be used to correlate metrics with test execution windows.
67
121
68
122
## Troubleshooting
69
123
124
+
If for whatever reason you are not seeing JMeter metrics in Datadog, check your `jmeter.log` file, which should be in the `/bin` folder of your JMeter installation.
125
+
126
+
#### Not Seeing `runner_id`?
127
+
128
+
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.
129
+
70
130
Need help? Contact [Datadog support][3].
71
131
72
132
## Further Reading
73
133
74
134
Additional helpful documentation, links, and articles:
0 commit comments