.. _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.