Datadog

This reporter supports sending metrics, events and traces to Datadog.

In order to enable the Datadog reporter set type to datadog as shown below:

plugins:
  publish-metrics:
    - type: datadog

Metrics

Metrics can be sent to an already running Datadog agent (opens in a new tab) or directly to Datadog API (opens in a new tab).

If Datadog agents have already been set up on your infrastructure, then publishing via the agent is probably preferable. Publishing via the HTTP API is useful when running in environments which do not have the agent (e.g. when running Artillery on AWS Lambda or AWS Fargate).

By default, all Artillery metrics will be sent to Datadog. Each Artillery metric will create a custom Datadog metric (opens in a new tab), which will have an associated charge.

You can configure a specific list of metrics to send with the includeOnly setting (see Configuration section below).

Configuration options

Example configuration

config:
  plugins:
    publish-metrics:
      - type: datadog
        # DD_API_KEY is an environment variable containing the API key
        apiKey: "{{ $env.DD_API_KEY }}"
        prefix: "artillery.publish_metrics_plugin."
        tags:
          - "testId:mytest123"
          - "reporterType:datadog-api"

Name	Description
`apiKey`	Set to an API key to send metrics directly to Datadog via its HTTP API.
`appKey` Added inv2.0.0-37	Application key (opens in a new tab)
`host`	Hostname/IP of the agent (defaults to `127.0.0.1`)
`port`	Port that the agent is listening on (defaults to `8125`)
`apiHost`	Use this to override the default Datadog endpoint, e.g. to use Datadog EU set the value to `app.datadoghq.eu` (default is `app.datadoghq.com`). Note: this only works when `apiKey` is set, and not when Datadog agent is used.
`prefix`	Use a prefix for metric names created by Artillery (defaults to `artillery.`).
`tags`	A list of `name:value` strings to use as tags for all metrics sent during a test
`excluded` Added inv2.0.0-30	A list of metric names which should not be sent to Datadog. Defaults to an empty list, i.e. all metrics are sent to Datadog.
`includeOnly` Added inv2.0.0-30	A list of specific metrics to send to Datadog. No other metrics will be sent. Defaults to an empty list, i.e. all metrics are sent to Datadog.
`event`	Set to send a Datadog event when test starts/finishes. See event specific configuration
`traces` Added inv2.0.5	Set to send traces to Datadog. See traces specific configuration

Note: If apiKey is not set, metrics will be sent to a Datadog agent

Events

The reporter supports sending a Datadog event on test start and test finish.

Configuration options

Example configuration

integration test" priority: normal tags: - "testId:mytest123" ```
</details>
 
| Name       | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| `title`    | Event title (defaults to `Artillery.io Test` + timestamp)               |
| `text`     | Event text                                                              |
| `priority` | Event priority. Valid options are `normal` or `low` (defaults to `low`) |
| `tags`     | A list of event specific tags in the `name:value` format                |
 
## Traces
 
<Version tag="artillery-2.0.5" />
*Powered by: [OpenTelemetry reporter](./opentelemetry)*
 
<Callout type="warning">
**Experimental** This feature is under active development. We aim to keep it
stable, but it may need to introduce breaking changes. Please open an
[issue](https://github.com/artilleryio/artillery/issues/new/choose) or
[discussion](https://github.com/artilleryio/artillery/discussions/new/choose)
for any feedback.
</Callout>
 
Datadog `tracing` feature is available for both [HTTP](../../engines/http) and [Playwright](../../engines/playwright) engines, and the [tracing data available](./opentelemetry#artillery-engines) is different depending on the engine used.
 
An additional `plugins.publish-metrics.spans.exported` metric will be recorded and will appear in your reports when `tracing` is enabled. It represents the number of spans exported to Datadog.
 
<Version tag="artillery-2.0.9" />
 
### Configuration options
 
Datadog requires a running instance of the Datadog Agent (or the OTel Collector configured with the Datadog exporter) in order to ingest traces. When you run a test on AWS Fargate, Artillery will take care of this for you automatically, but for testing on your local machine you will need to run the agent yourself. Below you will find a quick quide for both AWS Fargate and local runs.<br/>
_Note: AWS Lambda is not currently supported._
 
<details>
<summary>Example configuration</summary>
 
```yaml
plugins:
publish-metrics:
  - type: 'datadog'
    traces:
      sampleRate: 0.5
      replaceSpanNameRegex:
        - pattern: get_user_[a-zA-Z0-9]+
          as: get_user_id
      tags:
        - 'testType:LoadTest'
        - 'tool:Artillery'

Name	Description
`serviceName`	Name of your service. Defaults to `Artillery-test`
`sampleRate`	Sample rate. Percentage of traces to send represented by a value between 0 and 1. (defaults to 1 - all traces are sent)
`useRequestNames`	If set to `true` the request `name`s provided in test script will be used as span names
`tags`	A list of custom tags to be added to each span in `key:value` format strings
`replaceSpanNameRegex` Added inv2.0.9	A list of replacement maps that consist of: `pattern` - regex pattern to match against the span names `as` - string to replace the matched pattern in the span names

AWS Fargate - additional setup

Artillery sets up the AWS Distro for OpenTelemetry (opens in a new tab) configured with the Datadog exporter as a sidecar container. For it to start, all you need to do is to make sure a DD_API_KEY is set in a .env file by using the --dotenv flag. Example:

artillery run-fargate scenario.yaml --dotenv ./.env

NOTE: If you're sending the metrics to Datadogs HTTP API and have therefore already provided the API key in the script with apiKey, you do not need to provide it through dotenv file.

Local runs - additional setup

You'll need to setup a Datadog Agent in your machine with the following environment variables:

| Key | Value | | ----------------------------------------------- | ------------------------------ | --- | | DD_API_KEY | Your Datadog API key | | DD_HOSTNAME | A unique name for your machine | | DD_SITE | datadoghq.com | | DD_APM_TRACE_BUFFER | 100 | | DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT | 0.0.0.0:4318 | |

To setup a Datadog agent using Docker:

Install Docker here (opens in a new tab)
Run the following Docker CLI command in a Terminal (Mac/Linux) or Command Prompt (Windows), making sure to replace DD_API_KEY and DD_HOSTNAME with the correct values:

docker run --rm \
	-e DD_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
	-e DD_HOSTNAME=ADD_A_UNIQUE_NAME_FOR_YOUR_MACHINE \
	-e DD_SITE="datadoghq.com" \
	-e DD_APM_TRACE_BUFFER=100 \
	-e DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318 \
	-p 4318:4318 \
	datadog/agent

Wait a few moments. You should start seeing logs while the agent starts up.
After that, you can run your Artillery script (example configuration below).

Demo

Here is a small demo (opens in a new tab) on seeing your Playwright engine traces on Datadog.

Debugging

Set DEBUG=plugin:publish-metrics:datadog-statsd when running your tests to print out helpful debugging messages when sending metrics to Datadog.

DEBUG=plugin:publish-metrics:datadog-statsd artillery run my-script.yaml

Examples

Datadog with an agent

config:
  plugins:
    publish-metrics:
      # apiKey not set, so the plugin will assume that the agent is running:
      - type: datadog
        prefix: 'artillery.publish_metrics_plugin.'
        tags:
          - 'reporterType:datadog-agent'
        event:
          priority: normal
          tags:
            - 'testId:mytest123'
        traces:
          useRequestNames: true
          tags:
            - 'testType:LoadTest'

Datadog with an API key

config:
  plugins:
    publish-metrics:
      - type: datadog
        # DD_API_KEY is an environment variable containing the API key
        apiKey: '{{ $env.DD_API_KEY }}'
        prefix: 'artillery.publish_metrics_plugin.'
        tags:
          - 'testId:mytest123'
          - 'reporterType:datadog-api'
        event:
          title: 'Plugin integration test'
          priority: normal
          tags:
            - 'testId:mytest123'
        traces:
          sampleRate: 0.5
          useRequestNames: true
          tags:
            - 'testType:LoadTest'

OpenTelemetry CloudWatch