Skip to main content
Version: Next

opentelemetry

Description#

The opentelemetry Plugin can be used to report tracing data according to the OpenTelemetry specification.

The Plugin only supports binary-encoded OLTP over HTTP.

Attributes#

NameTypeRequiredDefaultValid valuesDescription
samplerobjectFalseSampling configuration.
sampler.namestringFalsealways_off["always_on", "always_off", "trace_id_ratio", "parent_base"]Sampling strategy. always_on: always samples, always_off: never samples, trace_id_ratio: random sampling result based on given sampling probability, parent_base: use parent decision if given, else determined by the root sampler.
sampler.optionsobjectFalse{fraction = 0, root = {name = "always_off"}}Parameters for sampling strategy.
sampler.options.fractionnumberFalse0[0, 1]Sampling probability for trace_id_ratio.
sampler.options.rootobjectFalse{name = "always_off", options = {fraction = 0}}Root sampler for parent_base strategy.
sampler.options.root.namestringFalsealways_off["always_on", "always_off", "trace_id_ratio"]Root sampling strategy.
sampler.options.root.optionsobjectFalse{fraction = 0}Root sampling strategy parameters.
sampler.options.root.options.fractionnumberFalse0[0, 1]Root sampling probability for trace_id_ratio.
additional_attributesarray[string]FalseVariables and its values which will be appended to the trace span.
additional_attributes[0]stringTrueAPISIX or Nginx variables. For example, http_header or route_id.
additional_header_prefix_attributesarray[string]FalseHeaders or headers prefixes to be appended to the trace span's attributes.
additional_header_prefix_attributes[0]stringTrueRequest headers. For example, x-my-header" or x-my-headers-* to include all headers with the prefix x-my-headers-.

Configuring the collector#

You can set up the collector by configuring it in you configuration file (conf/config.yaml):

NameTypeDefaultDescription
trace_id_sourceenumrandomSource 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}.
resourceobjectAdditional resource appended to the trace.
collectorobject{address = "127.0.0.1:4318", request_timeout = 3}OpenTelemetry Collector configuration.
collector.addressstring127.0.0.1:4318Collector address. If the collector serves on https, use https://127.0.0.1:4318 as the address.
collector.request_timeoutinteger3Report request timeout in seconds.
collector.request_headersobjectReport request HTTP headers.
batch_span_processorobjectTrace span processor.
batch_span_processor.drop_on_queue_fullbooleantrueWhen set to true, drops the span when queue is full. Otherwise, force process batches.
batch_span_processor.max_queue_sizeinteger2048Maximum queue size for buffering spans for delayed processing.
batch_span_processor.batch_timeoutnumber5Maximum time in seconds for constructing a batch.
batch_span_processor.max_export_batch_sizeinteger256Maximum number of spans to process in a single batch.
batch_span_processor.inactive_timeoutnumber2Time interval in seconds between processing batches.

You can configure these as shown below:

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
batch_span_processor:
drop_on_queue_full: false
max_queue_size: 6
batch_timeout: 2
inactive_timeout: 1
max_export_batch_size: 2

Enabling the Plugin#

To enable the Plugin, you have to add it to your configuration file (conf/config.yaml):

conf/config.yaml
plugins:
- ...
- opentelemetry

Now, you can enable the Plugin on a specific Route:

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
"/uid/*"
],
"plugins": {
"opentelemetry": {
"sampler": {
"name": "always_on"
}
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'

Disable Plugin#

To disable 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.

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
"/uid/*"
],
"plugins": {
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'