OpenTelemetry tracer (proto)

config.trace.v3.OpenTelemetryConfig

[config.trace.v3.OpenTelemetryConfig proto]

Configuration for the OpenTelemetry tracer.

This extension has the qualified name envoy.tracers.opentelemetry

Note

This extension is work-in-progress. Functionality is incomplete and it is not intended for production use.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.tracers

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.config.trace.v3.OpenTelemetryConfig

{
  "grpc_service": {...},
  "http_service": {...},
  "service_name": ...,
  "resource_detectors": [],
  "sampler": {...},
  "max_cache_size": {...},
  "set_telemetry_sdk_resource_attributes": {...},
  "set_service_name_resource_attribute": {...},
  "set_instrumentation_scope": {...},
  "incoming_trace_context": [],
  "outgoing_trace_context": []
}

grpc_service: (config.core.v3.GrpcService) The upstream gRPC cluster that will receive OTLP traces. Note that the tracer drops traces if the server does not read data fast enough. This field can be left empty to disable reporting traces to the gRPC service. Only one of grpc_service, http_service, exporter may be used.

http_service: (config.core.v3.HttpService) The upstream HTTP cluster that will receive OTLP traces. This field can be left empty to disable reporting traces to the HTTP service. Only one of grpc_service, http_service, exporter may be used.

Note

The request_headers_to_add property in the OTLP HTTP exporter service supports substitution formatters. The formatters cannot access any HTTP or connection properties, but can load content such as environment variables or files or secrets.

service_name: (string) The name for the service. This will be populated in the ResourceSpan Resource attributes. If it is not provided, it will default to “unknown_service:envoy”.

resource_detectors

(repeated config.core.v3.TypedExtensionConfig) An ordered list of resource detectors

Tip

This extension category has the following known extensions:

sampler

(config.core.v3.TypedExtensionConfig) Specifies the sampler to be used by the OpenTelemetry tracer. The configured sampler implements the Sampler interface defined by the OpenTelemetry specification. This field can be left empty. In this case, the default Envoy sampling decision is used.

See: OpenTelemetry sampler specification

Tip

This extension category has the following known extensions:

max_cache_size: (UInt32Value) Envoy caches the span in memory when the OpenTelemetry backend service is temporarily unavailable. This field specifies the maximum number of spans that can be cached. If not specified, the default is 1024.

set_telemetry_sdk_resource_attributes

(BoolValue) Specifies whether to set the telemetry SDK resource attributes. The following attributes will be set:

telemetry.sdk.language
telemetry.sdk.name
telemetry.sdk.version

If not specified, the default is to set these attributes.

set_service_name_resource_attribute: (BoolValue) Specifies whether to set the service.name resource attribute. If not specified, the default is to set this attribute.

set_instrumentation_scope: (BoolValue) Specifies whether to set the instrumentation scope name (“envoy”) and version on emitted traces. If not specified, the default is to set the instrumentation scope name and version.

incoming_trace_context

(repeated config.trace.v3.OpenTelemetryConfig.TraceContextFormat) The trace context formats to extract from downstream requests, in order of precedence. The first format whose headers are present and valid is used as the parent of the span; the remaining formats are ignored. A format whose headers are malformed is skipped. If headers were present but none of them could be extracted, the request is not traced.

B3 trace context without a sampling decision joins the trace, and the span’s sampling decision is made by Envoy as if it were the first span in the trace.

B3 headers that carry a decision not to sample but no trace context, such as b3: 0 or x-b3-sampled: 0 without x-b3-traceid and x-b3-spanid, start a new trace that is not sampled, regardless of Envoy’s tracing decision or the configured sampler. A decision to sample without trace context is ignored.

Each format may be listed at most once. If not specified, the default is [TRACE_CONTEXT].

outgoing_trace_context

(repeated config.trace.v3.OpenTelemetryConfig.TraceContextFormat) The trace context formats to inject into upstream requests. Headers of formats that are not listed are left unchanged, except that injecting either B3 encoding also rewrites headers of the other B3 encoding that are already on the request.

Each format may be listed at most once. If not specified, the default is [TRACE_CONTEXT].

Enum config.trace.v3.OpenTelemetryConfig.TraceContextFormat

[config.trace.v3.OpenTelemetryConfig.TraceContextFormat proto]

Trace context formats that can be extracted from downstream requests and injected into upstream requests.

TRACE_CONTEXT: (DEFAULT) ⁣W3C Trace Context: the traceparent and tracestate headers. See W3C Trace Context.

B3

⁣B3 single header: the b3 header. See B3 propagation.

When extracting, both the single header and the multiple header encodings are accepted, with the single header taking precedence. When injecting, the single header is written, and any x-b3-* headers already on the request are rewritten so that they describe the same span.

B3_MULTI

⁣B3 multiple headers: the x-b3-traceid, x-b3-spanid, x-b3-sampled and x-b3-flags headers. See B3 propagation.

When extracting, both the single header and the multiple header encodings are accepted, with the single header taking precedence. When injecting, x-b3-traceid, x-b3-spanid and x-b3-sampled are written, and a b3 header already on the request is rewritten so that it describes the same span.