Skip to main content
API7.ai Logo

Parameters​

See plugin common configurations for configuration options available to all plugins.

  • sampler

    object

    Sampling configuration.

    • name

      string

      default: always_off

      vaild vaule:

      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 follow the parent span's sampling decision, use parent_base. If there is no parent span, the root sampler determines the decision.

    • options

      object

      Parameters for sampling strategy.

      • fraction

        number

        default: 0

        Sampling fraction when the strategy is trace_id_ratio. Values less than 0 are treated as 0, while values greater than or equal to 1 sample every trace.

      • root

        object

        Root sampler used when the strategy is parent_base and the span has no parent.

        • name

          string

          default: always_off

          vaild vaule:

          always_on, always_off, or trace_id_ratio

          Root sampling strategy.

        • options

          object

          Root sampling strategy parameters.

          • fraction

            number

            default: 0

            Root sampling fraction when the strategy is trace_id_ratio. Values less than 0 are treated as 0, while values greater than or equal to 1 sample every trace.

  • additional_attributes

    array[string]

    Names of built-in variables 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]

    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​

  • trace_id_source

    string

    default: random

    vaild vaule:

    x-request-id or random

    Source of the trace ID. With x-request-id, supply a nonzero 32-character hexadecimal trace ID. APISIX 3.18.0 and API7 Gateway 3.10.7 normalize and validate the candidate, falling back to a generated trace ID when it is invalid. API7 Gateway 3.9.20 does not validate an explicitly supplied header; when the header is absent, it uses the NGINX request ID.

  • resource

    object

    Resource attributes to add to every span, for example, {"service.name": "APISIX"}. If the object is present without service.name, the plugin adds service.name: APISIX.

  • collector

    object

    Collector configurations.

    • address

      string

      default: 127.0.0.1:4318

      Base address of the OpenTelemetry Collector. The plugin appends /v1/traces and uses HTTP when the address does not include a scheme.

    • request_timeout

      integer

      default: 3

      Request timeout to the OpenTelemetry Collector in seconds.

    • request_headers

      object

      Request headers to include when sending traces to the OpenTelemetry Collector, such as {"Authorization": "token"}.

  • batch_span_processor

    object

    Batch span processor configurations.

    • drop_on_queue_full

      boolean

      default: true

      If true, drop new spans when the queue is full. If false, process queued batches to make room.

    • max_queue_size

      integer

      default: 2048

      vaild vaule:

      greater than max_export_batch_size

      Maximum number of spans to buffer for delayed processing.

    • batch_timeout

      number

      default: 5

      vaild vaule:

      greater than 0

      Maximum time in seconds to wait while constructing a batch.

    • inactive_timeout

      number

      default: 2

      vaild vaule:

      greater than 0

      Interval in seconds for processing queued batches when the queue is not full.

    • max_export_batch_size

      integer

      default: 256

      vaild vaule:

      greater than 0 and less than max_queue_size

      Maximum number of spans to process in one exported batch.

  • set_ngx_var

    boolean

    default: false

    If true, populate the opentelemetry_context_traceparent, opentelemetry_trace_id, and opentelemetry_span_id NGINX variables.