# Observability > Datadog # Datadog Artillery provides comprehensive integration with Datadog, supporting metrics, traces, and events through both native integration ([Datadog API](https://docs.datadoghq.com/api/) or [Datadog Agent](https://docs.datadoghq.com/agent/)) and OpenTelemetry. Note on choosing a specific integration type for Datadog: * **Datadog HTTP API** - the easiest integration to set up as it only needs an API key and works everywhere. Only supports metrics and events. * **Datadog agent** - requires a running installation of the agent. Artillery automatically makes this work on AWS Fargate (when using the `run-ecs`/`run-fargate` command). It also works locally & or on infra where you can install it (e.g. single instances of Artillery on a Kubernetes cluster). The Datadog agent is the default and best-supported method to send OpenTelemetry data to Datadog. Supports metrics and traces. * **OTLP intake endpoints** - only supports metrics at the moment. See https://docs.datadoghq.com/opentelemetry/setup/otlp\_ingest/metrics for details. ## Quick Start #### Tab \`config: plugins: publish-metrics: \- type: datadog apiKey: "\{\{ $env.DD\_API\_KEY }}"\` #### Tab \`config: plugins: publish-metrics: \- type: open-telemetry serviceName: 'my\_service' metrics: attributes: environment: 'test' traces: \{}\` ## Configuration Methods ### Native Integration The native Datadog reporter supports sending [metrics](#metrics), [events](#events) and [traces](#traces-native) to Datadog. ```yaml plugins: publish-metrics: - type: datadog ``` #### Metrics Metrics can be sent to an already running Datadog [agent](https://docs.datadoghq.com/agent/) or directly to [Datadog API](https://docs.datadoghq.com/api/). By default, all Artillery metrics will be sent to Datadog. Each Artillery metric will create a [custom Datadog metric](https://docs.datadoghq.com/account_management/billing/custom_metrics/?tab=countrate), which will have an associated charge. #### Configuration Options | Name | Description | |------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `apiKey` | Set to an API key to send metrics directly to Datadog via its HTTP API. | | `appKey` | [Application key](https://docs.datadoghq.com/account_management/api-app-keys/#application-keys) | | `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` | 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` | 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](#events) | | `traces` | Set to send traces to Datadog. See [traces specific configuration](#traces-native) | > **Info:** *Note: If `apiKey` is not set, metrics will be sent to a Datadog agent* #### Events The reporter supports sending a Datadog event when a test starts and finishes. #### Event Configuration | 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 | Example: ```yaml config: plugins: publish-metrics: - type: datadog event: title: "Plugin integration test" priority: normal tags: - 'testId:{{ $testId }}' ``` #### Traces Datadog tracing feature is available for both [HTTP](../../engines/http) and [Playwright](../../engines/playwright) engines. #### Trace Configuration Options | 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` | 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 | Example: ```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' ``` ##### Setup Requirements **AWS Fargate** Artillery sets up the [AWS Distro for OpenTelemetry](https://aws-otel.github.io/) 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 `--env-file` flag: ```sh artillery run-fargate scenario.yaml --env-file .env ``` **Local runs** You'll need to setup a Datadog Agent with these 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 | Using Docker: ```sh 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 ``` ### OpenTelemetry Integration You can also send data to Datadog using OpenTelemetry protocol. This is useful when you want standardized telemetry or are already using OpenTelemetry in your infrastructure. #### Configuration ```yaml plugins: publish-metrics: - type: 'open-telemetry' serviceName: 'my_service' metrics: attributes: environment: 'test' type: 'Load test' traces: {} ``` #### Fargate - Additional Setup Artillery sets up the Datadog Agent for you as a sidecar container. For it to start, all you need to do is make sure a `DD_API_KEY` is set in a `.env` file by using the `--env-file` flag: ```sh artillery run-fargate scenario.yaml --env-file .env ``` #### Local Runs - Additional Setup You'll need to setup a Datadog Agent in your machine. You can follow this [guide](https://artillery.notion.site/Playwright-tracing-with-Datadog-local-set-up-bb23b137915b48aa80854afbc5a8b726) to set it up using Docker. ## Examples ### Complete Native Integration ```yaml 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' ``` ### With Datadog Agent ```yaml 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' ``` ## Debugging Set `DEBUG=plugin:publish-metrics:datadog-statsd` when running your tests to print out helpful debugging messages when sending metrics to Datadog. ```sh DEBUG=plugin:publish-metrics:datadog-statsd artillery run my-script.yaml ``` ## Best Practices In addition to following a [tagging convention](../../../get-started/best-practices#create-tagging-conventions), we recommend using the tags from Datadog's [Unified Service Tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) for additional benefits in integrating with your existing Datadog setup.