.. _envoy_v3_api_file_envoy/config/trace/v3/trace.proto: Tracing ======= Tracing :ref:`architecture overview <arch_overview_tracing>`. .. _envoy_v3_api_msg_config.trace.v3.Tracing: config.trace.v3.Tracing ----------------------- `[config.trace.v3.Tracing proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L28>`_ The tracing configuration specifies global settings for the HTTP tracer used by Envoy. The configuration is defined by the :ref:`Bootstrap <envoy_v3_api_msg_config.bootstrap.v3.Bootstrap>` :ref:`tracing <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.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_v3_api_field_config.trace.v3.Tracing.http: http (:ref:`config.trace.v3.Tracing.Http <envoy_v3_api_msg_config.trace.v3.Tracing.Http>`) Provides configuration for the HTTP tracer. .. _envoy_v3_api_msg_config.trace.v3.Tracing.Http: config.trace.v3.Tracing.Http ---------------------------- `[config.trace.v3.Tracing.Http proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L31>`_ .. code-block:: json { "name": "...", "typed_config": "{...}" } .. _envoy_v3_api_field_config.trace.v3.Tracing.Http.name: name (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *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_v3_api_field_config.trace.v3.Tracing.Http.typed_config: typed_config (`Any <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any>`_) Trace driver specific configuration which depends on the driver being instantiated. See the trace drivers for examples: - :ref:`LightstepConfig <envoy_v3_api_msg_config.trace.v3.LightstepConfig>` - :ref:`ZipkinConfig <envoy_v3_api_msg_config.trace.v3.ZipkinConfig>` - :ref:`DynamicOtConfig <envoy_v3_api_msg_config.trace.v3.DynamicOtConfig>` - :ref:`DatadogConfig <envoy_v3_api_msg_config.trace.v3.DatadogConfig>` - :ref:`OpenCensusConfig <envoy_v3_api_msg_config.trace.v3.OpenCensusConfig>` - :ref:`AWS X-Ray <envoy_v3_api_msg_config.trace.v3.XRayConfig>` .. _envoy_v3_api_msg_config.trace.v3.LightstepConfig: config.trace.v3.LightstepConfig ------------------------------- `[config.trace.v3.LightstepConfig proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L70>`_ Configuration for the LightStep tracer. .. _extension_envoy.tracers.lightstep: 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. .. code-block:: json { "collector_cluster": "...", "access_token_file": "..." } .. _envoy_v3_api_field_config.trace.v3.LightstepConfig.collector_cluster: collector_cluster (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) The cluster manager cluster that hosts the LightStep collectors. .. _envoy_v3_api_field_config.trace.v3.LightstepConfig.access_token_file: access_token_file (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) File containing the access token to the `LightStep <https://lightstep.com/>`_ API. .. _envoy_v3_api_msg_config.trace.v3.ZipkinConfig: config.trace.v3.ZipkinConfig ---------------------------- `[config.trace.v3.ZipkinConfig proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L85>`_ Configuration for the Zipkin tracer. .. _extension_envoy.tracers.zipkin: 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. .. code-block:: json { "collector_cluster": "...", "collector_endpoint": "...", "trace_id_128bit": "...", "shared_span_context": "{...}", "collector_endpoint_version": "..." } .. _envoy_v3_api_field_config.trace.v3.ZipkinConfig.collector_cluster: collector_cluster (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *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_v3_api_field_config.bootstrap.v3.Bootstrap.StaticResources.clusters>`. .. _envoy_v3_api_field_config.trace.v3.ZipkinConfig.collector_endpoint: collector_endpoint (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *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_v3_api_field_config.trace.v3.ZipkinConfig.trace_id_128bit: trace_id_128bit (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 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_v3_api_field_config.trace.v3.ZipkinConfig.shared_span_context: shared_span_context (`BoolValue <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#boolvalue>`_) Determines whether client and server spans will share the same span context. The default value is true. .. _envoy_v3_api_field_config.trace.v3.ZipkinConfig.collector_endpoint_version: collector_endpoint_version (:ref:`config.trace.v3.ZipkinConfig.CollectorEndpointVersion <envoy_v3_api_enum_config.trace.v3.ZipkinConfig.CollectorEndpointVersion>`) Determines the selected collector endpoint version. By default, the ``HTTP_JSON_V1`` will be used. .. _envoy_v3_api_enum_config.trace.v3.ZipkinConfig.CollectorEndpointVersion: Enum config.trace.v3.ZipkinConfig.CollectorEndpointVersion ---------------------------------------------------------- `[config.trace.v3.ZipkinConfig.CollectorEndpointVersion proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L89>`_ Available Zipkin collector endpoint versions. .. _envoy_v3_api_enum_value_config.trace.v3.ZipkinConfig.CollectorEndpointVersion.DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE: DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE *(DEFAULT)* Zipkin API v1, JSON over HTTP. .. _envoy_v3_api_enum_value_config.trace.v3.ZipkinConfig.CollectorEndpointVersion.HTTP_JSON: HTTP_JSON Zipkin API v2, JSON over HTTP. .. _envoy_v3_api_enum_value_config.trace.v3.ZipkinConfig.CollectorEndpointVersion.HTTP_PROTO: HTTP_PROTO Zipkin API v2, protobuf over HTTP. .. _envoy_v3_api_msg_config.trace.v3.DynamicOtConfig: config.trace.v3.DynamicOtConfig ------------------------------- `[config.trace.v3.DynamicOtConfig proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L137>`_ DynamicOtConfig is used to dynamically load a tracer from a shared library that implements the `OpenTracing dynamic loading API <https://github.com/opentracing/opentracing-cpp>`_. .. _extension_envoy.tracers.dynamic_ot: 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. .. code-block:: json { "library": "...", "config": "{...}" } .. _envoy_v3_api_field_config.trace.v3.DynamicOtConfig.library: library (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) Dynamic library implementing the `OpenTracing API <https://github.com/opentracing/opentracing-cpp>`_. .. _envoy_v3_api_field_config.trace.v3.DynamicOtConfig.config: config (`Struct <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`_) The configuration to use when creating a tracer from the given dynamic library. .. _envoy_v3_api_msg_config.trace.v3.DatadogConfig: config.trace.v3.DatadogConfig ----------------------------- `[config.trace.v3.DatadogConfig proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L152>`_ Configuration for the Datadog tracer. .. _extension_envoy.tracers.datadog: 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. .. code-block:: json { "collector_cluster": "...", "service_name": "..." } .. _envoy_v3_api_field_config.trace.v3.DatadogConfig.collector_cluster: collector_cluster (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) The cluster to use for submitting traces to the Datadog agent. .. _envoy_v3_api_field_config.trace.v3.DatadogConfig.service_name: service_name (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) The name used for the service when traces are generated by envoy. .. _envoy_v3_api_msg_config.trace.v3.OpenCensusConfig: config.trace.v3.OpenCensusConfig -------------------------------- `[config.trace.v3.OpenCensusConfig proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L166>`_ Configuration for the OpenCensus tracer. .. _extension_envoy.tracers.opencensus: 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. .. 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_v3_api_field_config.trace.v3.OpenCensusConfig.trace_config: trace_config (.opencensus.proto.trace.v1.TraceConfig) Configures tracing, e.g. the sampler, max number of annotations, etc. .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.stdout_exporter_enabled: stdout_exporter_enabled (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Enables the stdout exporter if set to true. This is intended for debugging purposes. .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.stackdriver_exporter_enabled: stackdriver_exporter_enabled (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Enables the Stackdriver exporter if set to true. The project_id must also be set. .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.stackdriver_project_id: stackdriver_project_id (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) The Cloud project_id to use for Stackdriver tracing. .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.stackdriver_address: stackdriver_address (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) (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_v3_api_field_config.trace.v3.OpenCensusConfig.zipkin_exporter_enabled: zipkin_exporter_enabled (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Enables the Zipkin exporter if set to true. The url and service name must also be set. .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.zipkin_url: zipkin_url (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) The URL to Zipkin, e.g. "http://127.0.0.1:9411/api/v2/spans" .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.ocagent_exporter_enabled: ocagent_exporter_enabled (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Enables the OpenCensus Agent exporter if set to true. The address must also be set. .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.ocagent_address: ocagent_address (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 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_v3_api_field_config.trace.v3.OpenCensusConfig.incoming_trace_context: incoming_trace_context (:ref:`config.trace.v3.OpenCensusConfig.TraceContext <envoy_v3_api_enum_config.trace.v3.OpenCensusConfig.TraceContext>`) List of incoming trace context headers we will accept. First one found wins. .. _envoy_v3_api_field_config.trace.v3.OpenCensusConfig.outgoing_trace_context: outgoing_trace_context (:ref:`config.trace.v3.OpenCensusConfig.TraceContext <envoy_v3_api_enum_config.trace.v3.OpenCensusConfig.TraceContext>`) List of outgoing trace context headers we will produce. .. _envoy_v3_api_enum_config.trace.v3.OpenCensusConfig.TraceContext: Enum config.trace.v3.OpenCensusConfig.TraceContext -------------------------------------------------- `[config.trace.v3.OpenCensusConfig.TraceContext proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L170>`_ .. _envoy_v3_api_enum_value_config.trace.v3.OpenCensusConfig.TraceContext.NONE: NONE *(DEFAULT)* No-op default, no trace context is utilized. .. _envoy_v3_api_enum_value_config.trace.v3.OpenCensusConfig.TraceContext.TRACE_CONTEXT: TRACE_CONTEXT W3C Trace-Context format "traceparent:" header. .. _envoy_v3_api_enum_value_config.trace.v3.OpenCensusConfig.TraceContext.GRPC_TRACE_BIN: GRPC_TRACE_BIN Binary "grpc-trace-bin:" header. .. _envoy_v3_api_enum_value_config.trace.v3.OpenCensusConfig.TraceContext.CLOUD_TRACE_CONTEXT: CLOUD_TRACE_CONTEXT "X-Cloud-Trace-Context:" header. .. _envoy_v3_api_enum_value_config.trace.v3.OpenCensusConfig.TraceContext.B3: B3 X-B3-* headers. .. _envoy_v3_api_msg_config.trace.v3.TraceServiceConfig: config.trace.v3.TraceServiceConfig ---------------------------------- `[config.trace.v3.TraceServiceConfig proto] <https://github.com/envoyproxy/envoy/blob/v1.13.1/api/envoy/config/trace/v3/trace.proto#L233>`_ Configuration structure. .. code-block:: json { "grpc_service": "{...}" } .. _envoy_v3_api_field_config.trace.v3.TraceServiceConfig.grpc_service: grpc_service (:ref:`config.core.v3.GrpcService <envoy_v3_api_msg_config.core.v3.GrpcService>`, *REQUIRED*) The upstream gRPC cluster that hosts the metrics service.