# Observability > Opentelemetry # OpenTelemetry Artillery can send data to any [OpenTelemetry](https://opentelemetry.io/)-compatible backend, including a self-hosted [OTel Collector](https://opentelemetry.io/docs/collector/). ## Configuration ### Requirements In most cases basic configuration will require: * OTLP endpoint for the metrics and/or traces * An auth key sent via a vendor-specific header ### Configuration Template ```yaml config: plugins: publish-metrics: - type: 'open-telemetry' serviceName: # Set attributes for all resources (metrics and traces): resourceAttributes: custom-attribute: some-value metrics: endpoint: '{{ $env.OTLP_METRICS_ENDPOINT }}' headers: : '{{ $env.API_KEY }}' traces: endpoint: '{{ $env.OTLP_TRACES_ENDPOINT }}' headers: : '{{ $env.API_KEY }}' ``` **Steps** * Set `serviceName` to the name of your service. It will apply to both `metrics` and `traces` * Specify signal types you want to send and configure them with: * `endpoint` for the signal type in question * `headers` in `key: value` format. (The authentication (e.g. API key) is usually provided via header of platform specific format) This information can be found in your chosen observability backends documentation. Obtaining the right configuration Look into your chosen observability platforms documentation for the following information: \*\*Signal type\*\* supported - make sure ingesting the signal type that you want to send ( \`traces\` and/or \`metrics\` ) is supported. \*\*Underlying transport protocol\*\* for OTLP supported ( \`HTTP/JSON\` , \`HTTP/protobuf\` or \`gRPC\` ) for each signal type ( \`metrics\` / \`traces\` ). You will need this information to understand if you need to override the reporters default \`exporter\` setting. Artillery defaults to OTLP \`HTTP/JSON\` but has exporters for all 3 OTLP options. \*\*OTLP API endpoints\*\* to send data to. Keep in mind that the endpoints will be different for \`metrics\` and \`traces\` . If the same endpoint is provided for both signal types, you will need to append the \`/v1/metrics\` or \`/v1/traces\` to it. \*\*Headers\*\* needed. Usually at least one header is needed for authentication. Any additional information that the platform might ask you to set e.g. specific attributes. ### Configuration options #### Example configuration ```yaml config: publish-metrics: - type: 'open-telemetry' serviceName: 'my service' metrics: exporter: 'otlp-http' endpoint: '{{ $env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT }}' headers: Api-Key: '{{ $env.API_KEY }}' attributes: environment: 'test' traces: exporter: 'otlp-proto' endpoint: '{{ $env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT }}' headers: Authorization: '{{ $env.API_KEY }}' replaceSpanNameRegex: - pattern: get_user_[a-zA-Z0-9]+ as: get_user_id attributes: environment: 'test' tool: 'Artillery' smartSampling: thresholds: firstByte: 500 ``` #### Main | Name | Valid options | Description | | ------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `serviceName` | string (defaults to `Artillery.test`) | Logical name of the service. Represents `service.name` resource attribute. Used for both `metrics` and `traces`. | | `metrics` | [`key:value` settings](#metrics) | Set this option to send and configure metrics | | `traces` | [`key:value` settings](#traces) | Set this option to send and configure traces | | `resourceAttributes` (added in ) | `key:value` pairs | Custom attributes to be added to all [OTel resources](https://opentelemetry.io/docs/languages/js/resources/) | #### Metrics | Name | Valid options | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | `exporter` | - \`otlp-http\` ( \`OTLP\` via \`HTTP/JSON\` )(default) - \`otlp-proto\` ( \`OTLP\` via \`HTTP/protobuf\` ) - \`otlp-grpc\` ( \`OTLP\` via \`gRPC\` ) | Exporter used to send metrics. | | `endpoint` | - \`http://localhost:4318/v1/metrics\` for HTTP - \`http://localhost:4317/v1/metrics\` for gRPC | OTLP endpoint for metric ingestion provided by your chosen observability platform. | | `headers` | `key: value` pairs | Platform specific headers. Tipically used for providing authentication. | | `excluded` | list of strings | A list of metric names which should not be sent. | | `includeOnly` | list of strings | A list of specific metrics to send. No other metrics will be sent. | | `attributes` | `key: value` pairs | Custom attributes to be added to all metrics. | #### Traces 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. | Name | Valid options | Description | | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `exporter` | - \`otlp-http\` ( \`OTLP\` via \`HTTP/JSON\` )(default) - \`otlp-proto\` ( \`OTLP\` via \`HTTP/protobuf\` ) - \`otlp-grpc\` ( \`OTLP\` via \`gRPC\` ) - \`zipkin\` ( \`OTLP\` via \`gRPC\` ) | Exporter used to send traces. | | `endpoint` | - Valid endpoint Defaults to: - \`http://localhost:4318/v1/traces\` for HTTP - \`http://localhost:4317/v1/traces\` for gRPC | Endpoint (`OTLP` or `zipkin`) for trace ingestion provided by your chosen observability platform. | | `headers` | `key:value` pairs | Platform specific headers. Tipically used for providing authentication. | | `sampleRate` | value between 0 and 1 (default 1) | Sample rate. Percentage of traces to send. | | `useRequestNames` | - true - false (default) | If `true` the request `name`s provided in test script will be used as span names | | `attributes` | `key:value` pairs | Custom attributes to be added to each span. | | `smartSampling` | [configuration settings](#smart-sampling) | Set to export only traces that have errors, HTTP status code over 400 or exceed `thresholds` set (if any thresholds are set) | | `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 | ##### Smart sampling (HTTP engine) When `smartSampling` is set for `traces`, only traces that are considered outliers will be exported. Traces that pass the following criteria are considered outliers: * Errors - any span with error status (e.g. request that failed due to an error) * HTTP Status Code 400 or more * Exceeded time to first byte ([TTFB](https://web.dev/articles/ttfb)) threshold (if set with `firstByte`) * Exceeded total request time threshold (if set with `total`) ```yaml traces: smartSampling: thresholds: firstByte: 500 total: 2000 ``` **Thresholds:** | Name | Value | Description | |----------------|-----------------------|--------------------------------| | `firstByte` | Number (milliseconds) | threshold for time to first byte ([TTFB](https://web.dev/articles/ttfb))| | `total` | Number (miliseconds) | threshold for total request time | Example configuration for smart sampling With the configuration shown below the reporter will export traces with: Errors HTTP Status 400 or more TTFB over 500 miliseconds Total time of request over 2000 miliseconds \`plugins: publish-metrics: \- type: 'open-telemetry' serviceName: \ traces: endpoint: '\{\{ $env.OTLP\_TRACES\_ENDPOINT }}' headers: \: '\{\{ $env.API\_KEY }}' smartSampling: thresholds: firstByte: 500 total: 2000\` *** Environment variables config options Some additional configuration options can be set through environment variables: | Environment Variable | Signal specific | Description | |-----------------------------------------|-----------------|-------------| | \`OTEL\_EXPORTER\_OTLP\_HEADERS\` | NO | Equivalent to \`headers\` in test script, set to the headers required by your chosen platform. | \`OTEL\_EXPORTER\_OTLP\_METRICS\_ENDPOINT\` | YES | OTLP API endpoint for metrics ingestion | \`OTEL\_EXPORTER\_OTLP\_TRACES\_ENDPOINT\` | YES | OTLP API endpoint for traces ingestion | \`OTEL\_EXPORTER\_OTLP\_CERTIFICATE\` | NO | The path to the file containing trusted root certificate to use when verifying an OTLP trace, metric, or log server's TLS credentials. By default the host platform's trusted root certificate is used. | | \`OTEL\_EXPORTER\_OTLP\_TRACES\_CERTIFICATE\` | YES | The path to the file containing trusted root certificate to use when verifying an OTLP trace server's TLS credentials. By default the host platform's trusted root certificate is used. | | \`OTEL\_EXPORTER\_OTLP\_METRICS\_CERTIFICATE\` | YES | The path to the file containing trusted root certificate to use when verifying an OTLP metrics server's TLS credentials. By default the host platform's trusted root certificate is used. | | \`OTEL\_EXPORTER\_OTLP\_CLIENT\_CERTIFICATE\` | NO | The path to the file containing trusted client certificate/chain for clients private key to use when verifying an OTLP trace, metric and log server's TLS credentials. Must provide a private client key when providing a certificate/chain. By default no chain file is used. | | \`OTEL\_EXPORTER\_OTLP\_TRACES\_CLIENT\_CERTIFICATE\` | NO | The path to the file containing trusted client certificate/chain for clients private key to use when verifying an OTLP trace server's TLS credentials. Must provide a private client key when providing a certificate/chain. By default no chain file is used. | | \`OTEL\_EXPORTER\_OTLP\_METRICS\_CLIENT\_CERTIFICATE\` | NO | The path to the file containing trusted client certificate/chain for clients private key to use when verifying an OTLP metrics server's TLS credentials. Must provide a private client key when providing a certificate/chain. By default no chain file is used. | | \`OTEL\_EXPORTER\_OTLP\_CLIENT\_KEY\` | NO | The path to the file containing private client key to use when verifying an OTLP trace, metric or log client's TLS credentials. Must provide a client certificate/chain when providing a private client key. By default no client key file is used. | | \`OTEL\_EXPORTER\_OTLP\_TRACES\_CLIENT\_KEY\` | YES | The path to the file containing private client key to use when verifying an OTLP trace client's TLS credentials. Must provide a client certificate/chain when providing a private client key. By default no client key file is used. | | \`OTEL\_EXPORTER\_OTLP\_METRICS\_CLIENT\_KEY\` | YES | The path to the file containing private client key to use when verifying an OTLP metric client's TLS credentials. Must provide a client certificate/chain when providing a private client key. By default no client key file is used. | Note: When using environment variables keep in mind that you still need to configure the reporter in the script. The minimum reporter configuration in the script will require specifying the type of signal to send. \` plugins: publish-metrics: \- type: "open-telemetry" metrics: \{} traces: \{}\` > **Info:** Some platforms may require you to install and configure the OTel Collector, or the platform's own agent. In those cases the information on how to install and configure the collector / agent will be provided in your chosen platform's documentation. > > On Artillery's side configuration will be the same or very similar - you will need to provide an `endpoint` and authentication through either the script or environment variables. ## Debugging Set `DEBUG=plugin:publish-metrics:open-telemetry` when running your tests to print out helpful debugging messages when sending metrics and/or traces with OpenTelemetry. ```sh DEBUG=plugin:publish-metrics:open-telemetry artillery run my-script.yaml ```