# Observability > Dynatrace # Dynatrace Artillery provides comprehensive integration with Dynatrace, supporting metrics, traces, and events through both native integration ([Dynatrace API](https://www.dynatrace.com/support/help/dynatrace-api/)) and OpenTelemetry. ## Quick Start #### Tab \`plugins: publish-metrics: \- type: dynatrace apiToken: "\{\{ $env.DT\_API\_TOKEN }}" envUrl: "\{\{ $env.DT\_ENVIRONMENT\_URL }}"\` #### Tab \`plugins: publish-metrics: \- type: open-telemetry serviceName: my-service metrics: exporter: otlp-proto endpoint: '\{\{ $env.DYNATRACE\_OTLP\_ENDPOINT }}/v1/metrics' headers: Authorization: 'Api-Token \{\{ $env.API\_ACCESS\_TOKEN }}'\` ## Configuration Methods ### Native Integration The native Dynatrace reporter supports sending [metrics](#metrics), [events](#events) and [traces](#traces-native) to Dynatrace. #### Metrics By default, all Artillery metrics will be sent to Dynatrace. Each Artillery metric will create a custom Dynatrace metric, which will have an associated charge. > **Info:** NOTE: If using `metrics-by-endpoint` plugin alongside this reporter, in order > for all of your metrics to be ingested successfully, set `useOnlyRequestNames` > to `true` (in `metrics-by-endpoint`'s config) and provide the `name` for each > of your requests. This is required as `metrics-by-endpoint` plugin by default > creates metric names with characters that are not supported by Dynatrace (e.g. > '/') and will be dropped on ingest. Keep Dynatrace's [metric key naming > requirements](https://www.dynatrace.com/support/help/extend-dynatrace/extend-metrics/reference/metric-ingestion-protocol#metric-key) > in mind when naming your requests and custom metrics as well. For information on how to manage data ingested through the Dynatrace Metric API consult [Dynatrace docs](https://www.dynatrace.com/support/help/dynatrace-api/environment-api/metric-v2/post-ingest-metrics). #### Configuration Options ```yaml config: plugins: publish-metrics: - type: dynatrace # DT_API_TOKEN is an environment variable containing the API key apiToken: "{{ $env.DT_API_TOKEN }}" envUrl: "{{ $env.DT_ENVIRONMENT_URL }}" prefix: "artillery." dimensions: - "service:my-service" - "host_id:1.2.3.4" ``` | Name | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `apiToken` (required) | The [access token](https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-authentication). Must have the proper scopes assigned to it for the data type you are sending (`metrics.ingest`, `events.ingest`, and/or `openTelemetryTrace.ingest`). | | `envUrl` (required) | Set to your Dynatrace environment URL. For *Managed*, *Dynatrace for Government* or *Environment ActiveGate* this URL is `https://{your-domain}/e/{your-environment-id}` ( In case of *Environment ActiveGate* `{your-domain}` represents your Activegate domain).For `SaaS` the URL is `https://{your-environment-id}.live.dynatrace.com` | | `prefix` | use a prefix for metric names created by Artillery; defaults to `artillery.` | | `dimensions` | a list of `name:value` strings to use as dimensions for all metrics sent during a test. | | `excluded` | A list of metric names which should not be sent to Dynatrace. Defaults to an empty list, i.e. all metrics are sent. | | `includeOnly` | A list of specific metrics to send to Dynatrace. No other metrics will be sent. Defaults to an empty list, i.e. all metrics are sent. | | `event` | Set to send a Dynatrace event when test starts/finishes. See [event specific configuration](#events) | | `traces` | Set to send traces to Dynatrace. See [traces specific configuration](#traces-native) | #### Events The reporter supports sending a Dynatrace event on test start and test finish. #### Event Configuration ```yaml config: plugins: publish-metrics: - type: dynatrace apiToken: "{{ $env.DT_API_TOKEN }}" envUrl: "{{ $env.DT_ENVIRONMENT_URL }}" event: title: "Loadtest" entitySelector: "type(SERVICE),entityName.equals(MyService)" properties: - "Tool:Artillery" - "Load per minute:100" - "Load pattern:production" ``` | Name | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | The title of the event. Defaults to `Artillery_io_Test`. | | `eventType` | The type of the event. It can be one of the values listed [here](https://www.dynatrace.com/support/help/dynatrace-api/environment-api/events-v2/post-event#request-body-objects). Defaults to `CUSTOM_INFO` | | `send` | Set to `false` to turn off the event. By default, if `event` is configured, it will be sent. This option makes it possible to turn event creation on/off on the fly (e.g. via an environment variable) | | `properties` | Optional list of `name:value` strings to use as properties for events sent during a test. By default Artillery sends the `Target: ` and `Phase: 'Test-Started' / 'Test-Finished'` properties. Any `properties` set in script will be sent in addition to the default ones. | | `entitySelector` | The [entity selector](https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/entity-selector) string, defining a set of Dynatrace entities to be associated with the event. Only entities that have been active within the last 24 hours can be selected. | #### Traces Dynatrace `tracing` feature is available for both [HTTP](../../engines/http) and [Playwright](../../engines/playwright) engines. An additional `plugins.publish-metrics.spans.exported` metric will be recorded and will appear in your reports when `tracing` is enabled. #### Trace Configuration Options ```yaml config: plugins: publish-metrics: - type: dynatrace apiToken: "{{ $env.DT_API_TOKEN }}" envUrl: "{{ $env.DT_ENVIRONMENT_URL }}" traces: serviceName: service_name sampleRate: 0.5 replaceSpanNameRegex: - pattern: get_user_[a-zA-Z0-9]+ as: get_user_id attributes: - "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 | | `attributes` | Custom attributes to be added to each span in `key: value` pair format. | | `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 | ### OpenTelemetry Integration You can also send data to Dynatrace using OpenTelemetry protocol. #### Requirements * API Access Token with [correct scopes](#api-access-token-scopes) * [Endpoints](#endpoints) * [Network requirements](https://docs.dynatrace.com/docs/shortlink/otel-getstarted-otlpexport#network-requirements-export-to-activegate) where needed *Note: this guide is only for sending traces to [ActiveGate](https://docs.dynatrace.com/docs/setup-and-configuration/dynatrace-activegate). In order to send traces to OneAgent consult the [Dynatrace documentation](https://docs.dynatrace.com/docs/shortlink/otel-getstarted-otlpexport#export-to-oneagent-traces-only)* #### Configuration ```yaml plugins: publish-metrics: - type: 'open-telemetry' serviceName: metrics: exporter: otlp-proto endpoint: '{{ $env.DYNATRACE_OTLP_ENDPOINT }}/v1/metrics' headers: Authorization: 'Api-Token {{ $env.API_ACCESS_TOKEN }}' traces: exporter: otlp-proto endpoint: '{{ $env.DYNATRACE_OTLP_ENDPOINT }}/v1/traces' headers: Authorization: 'Api-Token {{ $env.API_ACCESS_TOKEN }}' ``` > **Info:** NOTE: Dynatrace only supports `HTTP/protobuf`, so we change the `exporter` > value from the default to `otlp-proto` in this case. #### Endpoints | ActiveGate Type | Base URL | | ------------------------------- | --------------------------------------------------------------------------- | | Dynatrace SaaS | `https://{your-environment-id}.live.dynatrace.com/api/v2/otlp` | | Local Environment ActiveGate(1) | `https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp` | > **Info:** Environment ActiveGates listen by default on port 9999. If you changed > that port, adjust the port in the URL accordingly. #### API Access Token Scopes To obtain an access token, in the Dynatrace web UI, go to **Access tokens**. Use the following access scopes for the signals you are exporting: | Signal Type | Access Scope | | ----------- | --------------------------- | | metrics | `metrics.ingest` | | traces | `openTelemetryTrace.ingest` | ## Examples ### Complete Native Integration ```yaml config: plugins: publish-metrics: - type: dynatrace apiToken: "{{ $env.DT_API_TOKEN }}" envUrl: "{{ $env.DT_ENVIRONMENT_URL }}" prefix: "artillery." dimensions: - "service:checkout" - "environment:production" event: title: "Load Test - Checkout Service" entitySelector: "type(SERVICE),entityName.equals(checkout-service)" properties: - "Tool:Artillery" - "TestType:Performance" traces: serviceName: checkout-service useRequestNames: true attributes: - "testId:{{ $testId }}" ``` ## Debugging Set `DEBUG=plugin:publish-metrics:dynatrace` when running your tests to print out helpful debugging messages when sending metrics to Dynatrace ```sh DEBUG=plugin:publish-metrics:dynatrace artillery run my-script.yaml ``` ## Reference For any additional information on OpenTelemetry data in Dynatrace, consult the [Dynatrace documentation](https://docs.dynatrace.com/docs/shortlink/otel-getstarted-otlpexport).