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:{{ $testId }}"
            - "reporterType:datadog-api"
NameDescription
apiKeySet 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)
hostHostname/IP of the agent (defaults to 127.0.0.1)
portPort that the agent is listening on (defaults to 8125)
apiHostUse 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.
prefixUse a prefix for metric names created by Artillery (defaults to artillery.).
tagsA 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.
eventSet 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
config:
  plugins:
    publish-metrics:
      - type: datadog
        event:
          title: "Plugin integration test"
          priority: normal
          tags:
            - 'testId:{{ $testId }}'
NameDescription
titleEvent title (defaults to Artillery.io Test + timestamp)
textEvent text
priorityEvent priority. Valid options are normal or low (defaults to low)
tagsA list of event specific tags in the name:value format

Traces

Added inv2.0.5

Powered by: OpenTelemetry reporter

⚠️

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 (opens in a new tab) or discussion (opens in a new tab) for any feedback.

Datadog tracing feature is available for both HTTP and Playwright engines, and the tracing data available 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.

Added inv2.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.

Note: AWS Lambda is not currently supported.

Example configuration
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'
NameDescription
serviceNameName of your service. Defaults to Artillery-test
sampleRateSample rate. Percentage of traces to send represented by a value between 0 and 1. (defaults to 1 - all traces are sent)
useRequestNamesIf set to true the request names provided in test script will be used as span names
tagsA 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:

KeyValue
DD_API_KEYYour Datadog API key
DD_HOSTNAMEA unique name for your machine
DD_SITEdatadoghq.com
DD_APM_TRACE_BUFFER100
DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT0.0.0.0:4318

To setup a Datadog agent using Docker:

  1. Install Docker here (opens in a new tab)
  2. 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
  1. Wait a few moments. You should start seeing logs while the agent starts up.
  2. 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

In addition to following a tagging convention, we recommend using the tags from Datadog's Unified Service Tagging (opens in a new tab) for additional benefits in integrating with your existing Datadog setup.

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:{{ $testId }}'
        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:{{ $testId }}'
          - 'reporterType:datadog-api'
        event:
          title: 'Plugin integration test'
          priority: normal
          tags:
            - 'testId:{{ $testId }}'
        traces:
          sampleRate: 0.5
          useRequestNames: true
          tags:
            - 'testType:LoadTest'