.. _envoy_api_file_envoy/config/trace/v2/trace.proto: Tracing ======= Tracing :ref:`architecture overview `. .. _envoy_api_msg_config.trace.v2.Tracing: config.trace.v2.Tracing ----------------------- `[config.trace.v2.Tracing proto] `_ The tracing configuration specifies global settings for the HTTP tracer used by Envoy. The configuration is defined by the :ref:`Bootstrap ` :ref:`tracing ` field. Envoy may support other tracers in the future, but right now the HTTP tracer is the only one supported. .. code-block:: json { "http": "{...}" } .. _envoy_api_field_config.trace.v2.Tracing.http: http (:ref:`config.trace.v2.Tracing.Http `) Provides configuration for the HTTP tracer. .. _envoy_api_msg_config.trace.v2.Tracing.Http: config.trace.v2.Tracing.Http ---------------------------- `[config.trace.v2.Tracing.Http proto] `_ .. code-block:: json { "name": "...", "config": "{...}", "typed_config": "{...}" } .. _envoy_api_field_config.trace.v2.Tracing.Http.name: 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.lightstep* - *envoy.zipkin* - *envoy.dynamic.ot* - *envoy.tracers.datadog* - *envoy.tracers.opencensus* - *envoy.tracers.xray* .. _envoy_api_field_config.trace.v2.Tracing.Http.config: config (`Struct `_) Trace driver specific configuration which depends on the driver being instantiated. See the trace drivers for examples: - :ref:`LightstepConfig ` - :ref:`ZipkinConfig ` - :ref:`DynamicOtConfig ` - :ref:`DatadogConfig ` - :ref:`OpenCensusConfig ` Only one of :ref:`config `, :ref:`typed_config ` may be set. .. _envoy_api_field_config.trace.v2.Tracing.Http.typed_config: typed_config (`Any `_) Trace driver specific configuration which depends on the driver being instantiated. See the trace drivers for examples: - :ref:`LightstepConfig ` - :ref:`ZipkinConfig ` - :ref:`DynamicOtConfig ` - :ref:`DatadogConfig ` - :ref:`OpenCensusConfig ` Only one of :ref:`config `, :ref:`typed_config ` may be set. .. _envoy_api_msg_config.trace.v2.LightstepConfig: config.trace.v2.LightstepConfig ------------------------------- `[config.trace.v2.LightstepConfig proto] `_ Configuration for the LightStep tracer. .. code-block:: json { "collector_cluster": "...", "access_token_file": "..." } .. _envoy_api_field_config.trace.v2.LightstepConfig.collector_cluster: collector_cluster (`string `_, *REQUIRED*) The cluster manager cluster that hosts the LightStep collectors. .. _envoy_api_field_config.trace.v2.LightstepConfig.access_token_file: access_token_file (`string `_, *REQUIRED*) File containing the access token to the `LightStep `_ API. .. _envoy_api_msg_config.trace.v2.ZipkinConfig: config.trace.v2.ZipkinConfig ---------------------------- `[config.trace.v2.ZipkinConfig proto] `_ Configuration for the Zipkin tracer. .. code-block:: json { "collector_cluster": "...", "collector_endpoint": "...", "trace_id_128bit": "...", "shared_span_context": "{...}", "collector_endpoint_version": "..." } .. _envoy_api_field_config.trace.v2.ZipkinConfig.collector_cluster: collector_cluster (`string `_, *REQUIRED*) The cluster manager cluster that hosts the Zipkin collectors. Note that the Zipkin cluster must be defined in the :ref:`Bootstrap static cluster resources `. .. _envoy_api_field_config.trace.v2.ZipkinConfig.collector_endpoint: 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. .. _envoy_api_field_config.trace.v2.ZipkinConfig.trace_id_128bit: 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. .. _envoy_api_field_config.trace.v2.ZipkinConfig.shared_span_context: shared_span_context (`BoolValue `_) Determines whether client and server spans will share the same span context. The default value is true. .. _envoy_api_field_config.trace.v2.ZipkinConfig.collector_endpoint_version: collector_endpoint_version (:ref:`config.trace.v2.ZipkinConfig.CollectorEndpointVersion `) Determines the selected collector endpoint version. By default, the ``HTTP_JSON_V1`` will be used. .. _envoy_api_enum_config.trace.v2.ZipkinConfig.CollectorEndpointVersion: Enum config.trace.v2.ZipkinConfig.CollectorEndpointVersion ---------------------------------------------------------- `[config.trace.v2.ZipkinConfig.CollectorEndpointVersion proto] `_ Available Zipkin collector endpoint versions. .. _envoy_api_enum_value_config.trace.v2.ZipkinConfig.CollectorEndpointVersion.HTTP_JSON_V1: HTTP_JSON_V1 *(DEFAULT)* ⁣Zipkin API v1, JSON over HTTP. .. _envoy_api_enum_value_config.trace.v2.ZipkinConfig.CollectorEndpointVersion.HTTP_JSON: HTTP_JSON ⁣Zipkin API v2, JSON over HTTP. .. _envoy_api_enum_value_config.trace.v2.ZipkinConfig.CollectorEndpointVersion.HTTP_PROTO: HTTP_PROTO ⁣Zipkin API v2, protobuf over HTTP. .. _envoy_api_msg_config.trace.v2.DynamicOtConfig: config.trace.v2.DynamicOtConfig ------------------------------- `[config.trace.v2.DynamicOtConfig proto] `_ DynamicOtConfig is used to dynamically load a tracer from a shared library that implements the `OpenTracing dynamic loading API `_. .. code-block:: json { "library": "...", "config": "{...}" } .. _envoy_api_field_config.trace.v2.DynamicOtConfig.library: library (`string `_, *REQUIRED*) Dynamic library implementing the `OpenTracing API `_. .. _envoy_api_field_config.trace.v2.DynamicOtConfig.config: config (`Struct `_) The configuration to use when creating a tracer from the given dynamic library. .. _envoy_api_msg_config.trace.v2.DatadogConfig: config.trace.v2.DatadogConfig ----------------------------- `[config.trace.v2.DatadogConfig proto] `_ Configuration for the Datadog tracer. .. code-block:: json { "collector_cluster": "...", "service_name": "..." } .. _envoy_api_field_config.trace.v2.DatadogConfig.collector_cluster: collector_cluster (`string `_, *REQUIRED*) The cluster to use for submitting traces to the Datadog agent. .. _envoy_api_field_config.trace.v2.DatadogConfig.service_name: service_name (`string `_, *REQUIRED*) The name used for the service when traces are generated by envoy. .. _envoy_api_msg_config.trace.v2.OpenCensusConfig: config.trace.v2.OpenCensusConfig -------------------------------- `[config.trace.v2.OpenCensusConfig proto] `_ Configuration for the OpenCensus tracer. .. code-block:: json { "trace_config": "{...}", "stdout_exporter_enabled": "...", "stackdriver_exporter_enabled": "...", "stackdriver_project_id": "...", "stackdriver_address": "...", "zipkin_exporter_enabled": "...", "zipkin_url": "...", "ocagent_exporter_enabled": "...", "ocagent_address": "...", "incoming_trace_context": [], "outgoing_trace_context": [] } .. _envoy_api_field_config.trace.v2.OpenCensusConfig.trace_config: trace_config (.opencensus.proto.trace.v1.TraceConfig) Configures tracing, e.g. the sampler, max number of annotations, etc. .. _envoy_api_field_config.trace.v2.OpenCensusConfig.stdout_exporter_enabled: stdout_exporter_enabled (`bool `_) Enables the stdout exporter if set to true. This is intended for debugging purposes. .. _envoy_api_field_config.trace.v2.OpenCensusConfig.stackdriver_exporter_enabled: stackdriver_exporter_enabled (`bool `_) Enables the Stackdriver exporter if set to true. The project_id must also be set. .. _envoy_api_field_config.trace.v2.OpenCensusConfig.stackdriver_project_id: stackdriver_project_id (`string `_) The Cloud project_id to use for Stackdriver tracing. .. _envoy_api_field_config.trace.v2.OpenCensusConfig.stackdriver_address: 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 .. _envoy_api_field_config.trace.v2.OpenCensusConfig.zipkin_exporter_enabled: zipkin_exporter_enabled (`bool `_) Enables the Zipkin exporter if set to true. The url and service name must also be set. .. _envoy_api_field_config.trace.v2.OpenCensusConfig.zipkin_url: zipkin_url (`string `_) The URL to Zipkin, e.g. "http://127.0.0.1:9411/api/v2/spans" .. _envoy_api_field_config.trace.v2.OpenCensusConfig.ocagent_exporter_enabled: ocagent_exporter_enabled (`bool `_) Enables the OpenCensus Agent exporter if set to true. The address must also be set. .. _envoy_api_field_config.trace.v2.OpenCensusConfig.ocagent_address: 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 .. _envoy_api_field_config.trace.v2.OpenCensusConfig.incoming_trace_context: incoming_trace_context (:ref:`config.trace.v2.OpenCensusConfig.TraceContext `) List of incoming trace context headers we will accept. First one found wins. .. _envoy_api_field_config.trace.v2.OpenCensusConfig.outgoing_trace_context: outgoing_trace_context (:ref:`config.trace.v2.OpenCensusConfig.TraceContext `) List of outgoing trace context headers we will produce. .. _envoy_api_enum_config.trace.v2.OpenCensusConfig.TraceContext: Enum config.trace.v2.OpenCensusConfig.TraceContext -------------------------------------------------- `[config.trace.v2.OpenCensusConfig.TraceContext proto] `_ .. _envoy_api_enum_value_config.trace.v2.OpenCensusConfig.TraceContext.NONE: NONE *(DEFAULT)* ⁣No-op default, no trace context is utilized. .. _envoy_api_enum_value_config.trace.v2.OpenCensusConfig.TraceContext.TRACE_CONTEXT: TRACE_CONTEXT ⁣W3C Trace-Context format "traceparent:" header. .. _envoy_api_enum_value_config.trace.v2.OpenCensusConfig.TraceContext.GRPC_TRACE_BIN: GRPC_TRACE_BIN ⁣Binary "grpc-trace-bin:" header. .. _envoy_api_enum_value_config.trace.v2.OpenCensusConfig.TraceContext.CLOUD_TRACE_CONTEXT: CLOUD_TRACE_CONTEXT ⁣"X-Cloud-Trace-Context:" header. .. _envoy_api_enum_value_config.trace.v2.OpenCensusConfig.TraceContext.B3: B3 ⁣X-B3-* headers. .. _envoy_api_msg_config.trace.v2.TraceServiceConfig: config.trace.v2.TraceServiceConfig ---------------------------------- `[config.trace.v2.TraceServiceConfig proto] `_ Configuration structure. .. code-block:: json { "grpc_service": "{...}" } .. _envoy_api_field_config.trace.v2.TraceServiceConfig.grpc_service: grpc_service (:ref:`core.GrpcService `, *REQUIRED*) The upstream gRPC cluster that hosts the metrics service.