OpenTelemetry Configuration
Configuration reference for the OpenTelemetry plugin (`opentelemetry`): the parameters and plugin metadata, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.
sampler — object · optional · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Sampling configuration.
name — string · optional · default: always_off · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Valid values: always_on, always_off, trace_id_ratio, or parent_base
Sampling strategy.
To always sample, use always_on.
To never sample, use always_off.
To randomly sample based on a given ratio, use trace_id_ratio.
To use to sampling decision of the span’s parent, use parent_base. If there is no parent, use the root sampler.
options — object · optional · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Parameters for sampling strategy.
fraction — number · optional · default: 0 · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Valid values: between 0 and 1 inclusive
Sampling ratio when the sampling strategy is trace_id_ratio.
root — object · optional · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Root sampler when the sampling strategy is parent_base strategy.
name — string · optional · default: always_off · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Valid values: always_on, always_off, or trace_id_ratio
Root sampling strategy.
options — object · optional · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Root sampling strategy parameters.
fraction — number · optional · default: 0 · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Valid values: between 0 and 1 inclusive
Root sampling ratio when the sampling strategy is trace_id_ratio.
additional_attributes — array[string] · optional · since APISIX 2.13.0 · API7 Gateway 3.2.7.1
Names of built-in variables (opens in Apache APISIX docs) to append to the trace span as string attributes. Values are resolved in the log phase, so variables populated late in request processing are available. Numeric and boolean values are converted to strings; boolean false is retained.
additional_header_prefix_attributes — array[string] · optional · since APISIX 2.99.0 · API7 Gateway 3.2.7.1
Headers or header prefixes appended to the trace span as string attributes in the log phase. For example, use x-my-header or x-my-headers-* to include all headers with the prefix x-my-headers-. Multiple values for one header are joined with , .
Plugin Metadata
tracing — boolean · optional · default: true
Global flag to enable or disable tracing. When set to false, no spans will be emitted regardless of per-route sampler configuration.
trace_id_source — string · optional · default: random · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Valid values: x-request-id or random
Source of the trace ID. When set to x-request-id, the value of the x-request-id header will be used as the trace ID.
resource — object · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Additional resource to append to the trace, for example, {"service_name": "APISIX"}.
collector — object · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Collector configurations.
address — string · optional · default: 127.0.0.1:4318 · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Address of the OpenTelemetry collector to send traces to.
request_timeout — integer · optional · default: 3 · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Request timeout to OpenTelemetry collector in seconds.
request_headers — object · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Request header to include in requests to OpenTelemetry collector, such as {"Authorization": "token"}.
batch_span_processor — object · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Batch span processor configurations.
drop_on_queue_full — boolean · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
If true, drop span when the queue is full, otherwise force process batches.
max_queue_size — integer · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Maximum queue size to buffer spans for delayed processing.
batch_timeout — number · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Timeout for span batches to wait in the export queue before being sent, in seconds.
inactive_timeout — number · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Timeout for spans to wait in the export queue before being sent, if the queue is not full, in seconds.
max_export_batch_size — integer · optional · since APISIX 3.12.0 · API7 Gateway 3.2.7.1
Maximum number of spans to include in a single batch sent to the OpenTelemetry collector.
set_ngx_var — boolean · optional · default: false · since APISIX 3.12.0 · API7 Gateway 3.2.16.3
Export opentelemetry variables to built-in variables (opens in Apache APISIX docs).