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_cluster: (string, REQUIRED) The cluster manager cluster that hosts the Zipkin collectors.

collector_endpoint: (string, REQUIRED) The API endpoint of the Zipkin service where the spans will be sent. When using a standard Zipkin installation.

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.

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.

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.