Project: APISIX (Orchestration & Management / API Gateway)
File: opentelemetry.md

title: opentelemetry keywords: Apache APISIX API Gateway Plugin OpenTelemetry description: This document contains information about the Apache opentelemetry Plugin. <!-- --> The `opentelemetry` Plugin can be used to report tracing data according to the . The Plugin only supports binary-encoded . | Name | Type | Required | Default | Valid values | Description | |||-|-|--|-| | sampler | object | False | | | Sampling configuration. | | sampler.name | string | False | alwaysoff | ["alwayson", "alwaysoff", "traceidratio", "parentbase"] | Sampling strategy. `alwayson`: always samples, `alwaysoff`: never samples, `traceidratio`: random sampling result based on given sampling probability, `parent_base`: use parent decision if given, else determined by the root sampler. | | sampler.options | object | False | | {fraction = 0, root = {name = "always_off"}} | Parameters for sampling strategy. | | sampler.options.fraction | number | False | 0 | [0, 1] | Sampling probability for `traceidratio`. | | sampler.options.root | object | False | {name = "alwaysoff", options = {fraction = 0}} | | Root sampler for `parentbase` strategy. | | sampler.options.root.name | string | False | alwaysoff | ["alwayson", "alwaysoff", "traceid_ratio"] | Root sampling strategy. | | sampler.options.root.options | object | False | {fraction = 0} | | Root sampling strategy parameters. | | sampler.options.root.options.fraction | number | False | 0 | [0, 1] | Root sampling probability for `traceidratio`. | | additionalattributes | array[string] | False | | | Additional attributes appended to the trace span. Support built-in NGINX or APISIX variables in values, such as `httpheader` or `route_id`. | | additionalheaderprefix_attributes | array[string] | False | | | Headers or header prefixes appended to the trace span's attributes. For example, use `x-my-header"` or `x-my-headers-*` to include all headers with the prefix `x-my-headers-`. | You can set up the collector by configuring it in you configuration file (`conf/config.yaml`): | Name | Type | Default | Description | |--|||-| | traceidsource | enum | random | Source of the trace ID. Valid values are `random` or `x-request-id`. When set to `x-request-id`, the value of the `x-request-id` header will be used as trace ID. Make sure that is matches the regex pattern `[0-9a-f]{32}`. | | resource | object | | Additional appended to the trace. | | collector | object | {address = "127.0.0.1:4318", request_timeout = 3} | OpenTelemetry Collector configuration. | | collector.address | string | 127.0.0.1:4318 | Collector

If the collector serves on https, use https://127.0.0.1:4318 as the address. | | collector.request_timeout | integer | 3 | Report request timeout in seconds. | | collector.request_headers | object | | Report request HTTP headers. | | batchspanprocessor | object | | Trace span processor. | | batchspanprocessor.droponqueue_full | boolean | true | When set to `true`, drops the span when queue is full. Otherwise, force process batches. | | batchspanprocessor.maxqueuesize | integer | 2048 | Maximum queue size for buffering spans for delayed processing. | | batchspanprocessor.batch_timeout | number | 5 | Maximum time in seconds for constructing a batch. | | batchspanprocessor.maxexportbatch_size | integer | 256 | Maximum number of spans to process in a single batch. | | batchspanprocessor.inactive_timeout | number | 2 | Time interval in seconds between processing batches. | You can configure these as shown below: ```yaml title="conf/config.yaml" plugin_attr: opentelemetry: resource: service.name: APISIX tenant.id: business_id collector: address: 192.168.8.211:4318 request_timeout: 3 request_headers: foo: bar batchspanprocessor: droponqueue_full: false maxqueuesize: 6 batch_timeout: 2 inactive_timeout: 1 maxexportbatch_size: 2 ``` The following nginx variables are set by OpenTelemetry: `opentelemetrycontexttraceparent` - , e.g.: `00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01` `opentelemetrytraceid` - Trace Id of the current span `opentelemetryspanid` - Span Id of the current span How to use variables? you have to add it to your configuration file (`conf/config.yaml`): ```yaml title="./conf/config.yaml" http: enableaccesslog: true access_log: "/dev/stdout" accesslogformat: '{"time": "$timeiso8601","opentelemetrycontexttraceparent": "$opentelemetrycontexttraceparent","opentelemetrytraceid": "$opentelemetrytraceid","opentelemetryspanid": "$opentelemetryspanid","remoteaddr": "$remote_addr","uri": "$uri"}' accesslogformat_escape: json plugins: opentelemetry plugin_attr: opentelemetry: setngxvar: true ``` To enable the Plugin, you have to add it to your configuration file (`conf/config.yaml`): ```yaml title="conf/config.yaml" plugins: ... opentelemetry ``` Now, you can enable the Plugin on a specific Route: :::note You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash adminkey=$(yq '.deployment.admin.adminkey[0].key' conf/config.yaml | sed 's/"//g') ``` ::: ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "methods": ["GET"], "uris": [ "/uid/*" ], "plugins": { "opentelemetry": { "sampler": { "name": "always_on" } } }, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }' ``` To remove the `opentelemetry` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "methods": ["GET"], "uris": [ "/uid/*" ], "plugins": { }, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }' ```