opentelemetry

Description

OpenTelemetry report Tracing data according to OpenTelemetry specification.

The plugin currently only supports binary-encoded OTLP over HTTP. For details, see OTLP/HTTP.

Attributes

NameTypeRequirementDefaultValidDescription
samplerobjectoptionalsampling config
sampler.namestringoptionalalways_off[“always_on”, “always_off”, “trace_id_ratio”, “parent_base”]sampling strategy，always_on：sampling all；always_off：sampling nothing；trace_id_ratio：base trace id percentage；parent_base：use parent decision, otherwise determined by root
sampler.optionsobjectoptional{fraction = 0, root = {name = “always_off”}}sampling strategy parameters
sampler.options.fractionnumberoptional0[0, 1]trace_id_ratio fraction
sampler.options.rootobjectoptional{name = “always_off”, options = {fraction = 0}}parent_base root sampler
sampler.options.root.namestringoptionalalways_off[“always_on”, “always_off”, “trace_id_ratio”]sampling strategy
sampler.options.root.optionsobjectoptional{fraction = 0}sampling strategy parameters
sampler.options.root.options.fractionnumberoptional0[0, 1]trace_id_ratio fraction
additional_attributesarray[string]optionalattributes (variable and its value) which will be appended to the trace span
additional_attributes[0]stringrequiredAPISIX or Nginx variable, like http_header or route_id

How To Enable

First of all, enable the opentelemetry plugin in the config.yaml:

  1. # Add this in config.yaml
  2. plugins:
  3.   - ... # plugin you need
  4.   - opentelemetry

Then reload APISIX.

Here’s an example, enable the opentelemetry plugin on the specified route:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "methods": ["GET"],
  4.     "uris": [
  5.         "/uid/*"
  6.     ],
  7.     "plugins": {
  8.         "opentelemetry": {
  9.             "sampler": {
  10.                 "name": "always_on"
  11.             }
  12.         }
  13.     },
  14.     "upstream": {
  15.         "type": "roundrobin",
  16.         "nodes": {
  17.             "10.110.149.175:8089": 1
  18.         }
  19.     }
  20. }'

How to set collecting

You can set the collecting by specifying the configuration in conf/config.yaml.

NameTypeDefaultDescription
trace_id_sourceenumrandomthe source of trace id, the valid value is random or x-request-id. If x-request-id is set, the value of x-request-id request header will be used as trace id. Please make sure it match regex pattern [0-9a-f]{32}
resourceobjectadditional resource append to trace
collectorobject{address = “127.0.0.1:4318”, request_timeout = 3}otlp collector
collector.addressstring127.0.0.1:4318collector address
collector.request_timeoutinteger3report request timeout(second)
collector.request_headersobjectreport request http headers
batch_span_processorobjecttrace span processor
batch_span_processor.drop_on_queue_fullbooleantruedrop span when queue is full, otherwise force process batches
batch_span_processor.max_queue_sizeinteger2048maximum queue size to buffer spans for delayed processing
batch_span_processor.batch_timeoutnumber5maximum duration(second) for constructing a batch
batch_span_processor.max_export_batch_sizeinteger256maximum number of spans to process in a single batch
batch_span_processor.inactive_timeoutnumber2timer interval(second) for processing batches

Here is an example:

  1. plugin_attr:
  2.   opentelemetry:
  3.     resource:
  4.       service.name: APISIX
  5.       tenant.id: business_id
  6.     collector:
  7.       address: 192.168.8.211:4318
  8.       request_timeout: 3
  9.       request_headers:
  10.         foo: bar
  11.     batch_span_processor:
  12.       drop_on_queue_full: false
  13.       max_queue_size: 6
  14.       batch_timeout: 2
  15.       inactive_timeout: 1
  16.       max_export_batch_size: 2

Disable Plugin

When you want to disable the opentelemetry plugin on a route/service, it is very simple, you can delete the corresponding JSON configuration in the plugin configuration, no need to restart the service, it will take effect immediately:

  1. $ curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "methods": ["GET"],
  4.     "uris": [
  5.         "/uid/*"
  6.     ],
  7.     "plugins": {
  8.     },
  9.     "upstream": {
  10.         "type": "roundrobin",
  11.         "nodes": {
  12.             "10.110.149.175:8089": 1
  13.         }
  14.     }
  15. }'