Zipkin tracer (proto)

config.trace.v3.ZipkinConfig

[config.trace.v3.ZipkinConfig proto]

Configuration for the Zipkin tracer.

This extension has the qualified name envoy.tracers.zipkin

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is 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.ZipkinConfig

{
  "collector_cluster": ...,
  "collector_endpoint": ...,
  "trace_id_128bit": ...,
  "shared_span_context": {...},
  "collector_endpoint_version": ...,
  "collector_hostname": ...,
  "split_spans_for_request": ...,
  "trace_context_option": ...,
  "collector_service": {...}
}

collector_cluster: (string) The cluster manager cluster that hosts the Zipkin collectors. Note: This field will be deprecated in future releases in favor of collector_service. Either this field or collector_service must be specified.

collector_endpoint: (string) The API endpoint of the Zipkin service where the spans will be sent. When using a standard Zipkin installation. Note: This field will be deprecated in future releases in favor of collector_service. Required when using collector_cluster.

trace_id_128bit: (bool) Determines whether a 128bit trace id will be used when creating a new trace instance. The default value is false, which will result in a 64 bit trace id being used.

shared_span_context: (BoolValue) Determines whether client and server spans will share the same span context. The default value is true.

collector_endpoint_version: (config.trace.v3.ZipkinConfig.CollectorEndpointVersion) Determines the selected collector endpoint version.

collector_hostname: (string) Optional hostname to use when sending spans to the collector_cluster. Useful for collectors that require a specific hostname. Defaults to collector_cluster above. Note: This field will be deprecated in future releases in favor of collector_service.

split_spans_for_request

(bool) If this is set to true, then Envoy will be treated as an independent hop in trace chain. A complete span pair will be created for a single request. Server span will be created for the downstream request and client span will be created for the related upstream request. This should be set to true in the following cases:

The Envoy Proxy is used as gateway or ingress.
The Envoy Proxy is used as sidecar but inbound traffic capturing or outbound traffic capturing is disabled.
Any case that the start_child_span of router is set to true.

Attention

If this is set to true, then the start_child_span of router SHOULD be set to true also to ensure the correctness of trace chain.

Both this field and start_child_span are deprecated by the spawn_upstream_span. Please use that spawn_upstream_span field to control the span creation.

trace_context_option: (config.trace.v3.ZipkinConfig.TraceContextOption) Determines which trace context format to use for trace header extraction and propagation. This controls both downstream request header extraction and upstream request header injection. Here is the spec for W3C trace headers: https://www.w3.org/TR/trace-context/ The default value is USE_B3 to maintain backward compatibility.

collector_service

(config.core.v3.HttpService) HTTP service configuration for the Zipkin collector. When specified, this configuration takes precedence over the legacy fields: collector_cluster, collector_endpoint, and collector_hostname. This provides a complete HTTP service configuration including cluster, URI, timeout, and headers. If not specified, the legacy fields above will be used for backward compatibility.

Required fields when using collector_service:

http_uri.cluster - Must be specified and non-empty
http_uri.uri - Must be specified and non-empty
http_uri.timeout - Optional

Full URI Support with Automatic Parsing:

The uri field supports both path-only and full URI formats:

tracing:
  provider:
    name: envoy.tracers.zipkin
    typed_config:
      "@type": type.googleapis.com/envoy.config.trace.v3.ZipkinConfig
      collector_service:
        http_uri:
          # Full URI format - hostname and path are extracted automatically
          uri: "https://zipkin-collector.example.com/api/v2/spans"
          cluster: zipkin
          timeout: 5s
        request_headers_to_add:
          - header:
              key: "X-Custom-Token"
              value: "your-custom-token"
          - header:
              key: "X-Service-ID"
              value: "your-service-id"

URI Parsing Behavior:

Full URI: "https://zipkin-collector.example.com/api/v2/spans"
- Hostname: zipkin-collector.example.com (sets HTTP Host header)
- Path: /api/v2/spans (sets HTTP request path)
Path only: "/api/v2/spans"
- Hostname: Uses cluster name as fallback
- Path: /api/v2/spans

Enum config.trace.v3.ZipkinConfig.TraceContextOption

[config.trace.v3.ZipkinConfig.TraceContextOption proto]

Available trace context options for handling different trace header formats.

USE_B3: (DEFAULT) ⁣Use B3 headers only (default behavior).

USE_B3_WITH_W3C_PROPAGATION: ⁣Enable B3 and W3C dual header support: - For downstream: Extract from B3 headers first, fallback to W3C traceparent if B3 is unavailable. - For upstream: Inject both B3 and W3C traceparent headers. When this option is NOT set, only B3 headers are used for both extraction and injection.

Enum config.trace.v3.ZipkinConfig.CollectorEndpointVersion

[config.trace.v3.ZipkinConfig.CollectorEndpointVersion proto]

Available Zipkin collector endpoint versions.

DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE: (DEFAULT) ⁣Zipkin API v1, JSON over HTTP.

HTTP_JSON: ⁣Zipkin API v2, JSON over HTTP.

HTTP_PROTO: ⁣Zipkin API v2, protobuf over HTTP.