Tracing¶

config.trace.v3.Tracing¶

The tracing configuration specifies global settings for the HTTP tracer used by Envoy. The configuration is defined by the Bootstrap tracing field. Envoy may support other tracers in the future, but right now the HTTP tracer is the only one supported.

{
  "http": "{...}"
}

http: (config.trace.v3.Tracing.Http) Provides configuration for the HTTP tracer.

config.trace.v3.Tracing.Http¶

[config.trace.v3.Tracing.Http proto]

{
  "name": "...",
  "typed_config": "{...}"
}

name

(string, REQUIRED) The name of the HTTP trace driver to instantiate. The name must match a supported HTTP trace driver. Built-in trace drivers:

envoy.tracers.lightstep
envoy.tracers.zipkin
envoy.tracers.dynamic_ot
envoy.tracers.datadog
envoy.tracers.opencensus
envoy.tracers.xray

typed_config

(Any) Trace driver specific configuration which depends on the driver being instantiated. See the trace drivers for examples:

LightstepConfig
ZipkinConfig
DynamicOtConfig
DatadogConfig
OpenCensusConfig
AWS X-Ray

config.trace.v3.LightstepConfig¶

[config.trace.v3.LightstepConfig proto]

Configuration for the LightStep tracer.

This extension may be referenced by the qualified name envoy.tracers.lightstep

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

{
  "collector_cluster": "...",
  "access_token_file": "...",
  "propagation_modes": []
}

collector_cluster: (string, REQUIRED) The cluster manager cluster that hosts the LightStep collectors.

access_token_file: (string, REQUIRED) File containing the access token to the LightStep API.

propagation_modes: (config.trace.v3.LightstepConfig.PropagationMode) Propagation modes to use by LightStep’s tracer.

Enum config.trace.v3.LightstepConfig.PropagationMode¶

[config.trace.v3.LightstepConfig.PropagationMode proto]

Available propagation modes

ENVOY: (DEFAULT) ⁣Propagate trace context in the single header x-ot-span-context.

LIGHTSTEP: ⁣Propagate trace context using LightStep’s native format.

B3: ⁣Propagate trace context using the b3 format.

TRACE_CONTEXT: ⁣Propagation trace context using the w3 trace-context standard.

config.trace.v3.ZipkinConfig¶

[config.trace.v3.ZipkinConfig proto]

Configuration for the Zipkin tracer.

This extension may be referenced by 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.

{
  "collector_cluster": "...",
  "collector_endpoint": "...",
  "trace_id_128bit": "...",
  "shared_span_context": "{...}",
  "collector_endpoint_version": "..."
}

collector_cluster: (string, REQUIRED) The cluster manager cluster that hosts the Zipkin collectors. Note that the Zipkin cluster must be defined in the Bootstrap static cluster resources.

collector_endpoint: (string, REQUIRED) The API endpoint of the Zipkin service where the spans will be sent. When using a standard Zipkin installation, the API endpoint is typically /api/v1/spans, which is the default value.

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. By default, the HTTP_JSON_V1 will be used.

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.

config.trace.v3.DynamicOtConfig¶

[config.trace.v3.DynamicOtConfig proto]

DynamicOtConfig is used to dynamically load a tracer from a shared library that implements the OpenTracing dynamic loading API.

This extension may be referenced by the qualified name envoy.tracers.dynamic_ot

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

{
  "library": "...",
  "config": "{...}"
}

library: (string, REQUIRED) Dynamic library implementing the OpenTracing API.

config: (Struct) The configuration to use when creating a tracer from the given dynamic library.

config.trace.v3.DatadogConfig¶

[config.trace.v3.DatadogConfig proto]

Configuration for the Datadog tracer.

This extension may be referenced by the qualified name envoy.tracers.datadog

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

{
  "collector_cluster": "...",
  "service_name": "..."
}

collector_cluster: (string, REQUIRED) The cluster to use for submitting traces to the Datadog agent.

service_name: (string, REQUIRED) The name used for the service when traces are generated by envoy.

config.trace.v3.OpenCensusConfig¶

[config.trace.v3.OpenCensusConfig proto]

Configuration for the OpenCensus tracer.

This extension may be referenced by the qualified name envoy.tracers.opencensus

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

{
  "trace_config": "{...}",
  "stdout_exporter_enabled": "...",
  "stackdriver_exporter_enabled": "...",
  "stackdriver_project_id": "...",
  "stackdriver_address": "...",
  "stackdriver_grpc_service": "{...}",
  "zipkin_exporter_enabled": "...",
  "zipkin_url": "...",
  "ocagent_exporter_enabled": "...",
  "ocagent_address": "...",
  "ocagent_grpc_service": "{...}",
  "incoming_trace_context": [],
  "outgoing_trace_context": []
}

trace_config: (.opencensus.proto.trace.v1.TraceConfig) Configures tracing, e.g. the sampler, max number of annotations, etc.

stdout_exporter_enabled: (bool) Enables the stdout exporter if set to true. This is intended for debugging purposes.

stackdriver_exporter_enabled: (bool) Enables the Stackdriver exporter if set to true. The project_id must also be set.

stackdriver_project_id: (string) The Cloud project_id to use for Stackdriver tracing.

stackdriver_address: (string) (optional) By default, the Stackdriver exporter will connect to production Stackdriver. If stackdriver_address is non-empty, it will instead connect to this address, which is in the gRPC format: https://github.com/grpc/grpc/blob/master/doc/naming.md

stackdriver_grpc_service: (config.core.v3.GrpcService) (optional) The gRPC server that hosts Stackdriver tracing service. Only Google gRPC is supported. If target_uri is not provided, the default production Stackdriver address will be used.

zipkin_exporter_enabled: (bool) Enables the Zipkin exporter if set to true. The url and service name must also be set.

zipkin_url: (string) The URL to Zipkin, e.g. “http://127.0.0.1:9411/api/v2/spans”

ocagent_exporter_enabled: (bool) Enables the OpenCensus Agent exporter if set to true. The ocagent_address or ocagent_grpc_service must also be set.

ocagent_address: (string) The address of the OpenCensus Agent, if its exporter is enabled, in gRPC format: https://github.com/grpc/grpc/blob/master/doc/naming.md

ocagent_grpc_service: (config.core.v3.GrpcService) (optional) The gRPC server hosted by the OpenCensus Agent. Only Google gRPC is supported. This is only used if the ocagent_address is left empty.

incoming_trace_context: (config.trace.v3.OpenCensusConfig.TraceContext) List of incoming trace context headers we will accept. First one found wins.

outgoing_trace_context: (config.trace.v3.OpenCensusConfig.TraceContext) List of outgoing trace context headers we will produce.

Enum config.trace.v3.OpenCensusConfig.TraceContext¶

[config.trace.v3.OpenCensusConfig.TraceContext proto]

NONE: (DEFAULT) ⁣No-op default, no trace context is utilized.

TRACE_CONTEXT: ⁣W3C Trace-Context format “traceparent:” header.

GRPC_TRACE_BIN: ⁣Binary “grpc-trace-bin:” header.

CLOUD_TRACE_CONTEXT: ⁣”X-Cloud-Trace-Context:” header.

B3: ⁣X-B3-* headers.

config.trace.v3.TraceServiceConfig¶

[config.trace.v3.TraceServiceConfig proto]

Configuration structure.

{
  "grpc_service": "{...}"
}

grpc_service: (config.core.v3.GrpcService, REQUIRED) The upstream gRPC cluster that hosts the metrics service.