data-plane-api/envoy/config/trace/v3/trace.proto

syntax = "proto3";

package envoy.config.trace.v3;

import "envoy/config/core/v3/grpc_service.proto";

import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

import "opencensus/proto/trace/v1/trace_config.proto";
import "udpa/annotations/versioning.proto";

import "envoy/annotations/deprecation.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.config.trace.v3";
option java_outer_classname = "TraceProto";
option java_multiple_files = true;

// [#protodoc-title: Tracing]
// Tracing :ref:`architecture overview <arch_overview_tracing>`.

// The tracing configuration specifies global
// settings for the HTTP tracer used by Envoy. The configuration is defined by
// the :ref:`Bootstrap <envoy_api_msg_config.bootstrap.v3.Bootstrap>` :ref:`tracing
// <envoy_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.
message Tracing {
  option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2.Tracing";

  message Http {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.config.trace.v2.Tracing.Http";

    reserved 2;

    reserved "config";

    // 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*
    string name = 1 [(validate.rules).string = {min_bytes: 1}];

    // Trace driver specific configuration which depends on the driver being instantiated.
    // See the trace drivers for examples:
    //
    // - :ref:`LightstepConfig <envoy_api_msg_config.trace.v3.LightstepConfig>`
    // - :ref:`ZipkinConfig <envoy_api_msg_config.trace.v3.ZipkinConfig>`
    // - :ref:`DynamicOtConfig <envoy_api_msg_config.trace.v3.DynamicOtConfig>`
    // - :ref:`DatadogConfig <envoy_api_msg_config.trace.v3.DatadogConfig>`
    // - :ref:`OpenCensusConfig <envoy_api_msg_config.trace.v3.OpenCensusConfig>`
    // - :ref:`AWS X-Ray <envoy_api_msg_config.trace.v3.XRayConfig>`
    oneof config_type {
      google.protobuf.Any typed_config = 3;
    }
  }

  // Provides configuration for the HTTP tracer.
  Http http = 1;
}

// Configuration for the LightStep tracer.
// [#extension: envoy.tracers.lightstep]
message LightstepConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.trace.v2.LightstepConfig";

  // The cluster manager cluster that hosts the LightStep collectors.
  string collector_cluster = 1 [(validate.rules).string = {min_bytes: 1}];

  // File containing the access token to the `LightStep
  // <https://lightstep.com/>`_ API.
  string access_token_file = 2 [(validate.rules).string = {min_bytes: 1}];
}

// Configuration for the Zipkin tracer.
// [#extension: envoy.tracers.zipkin]
// [#next-free-field: 6]
message ZipkinConfig {
  option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2.ZipkinConfig";

  // Available Zipkin collector endpoint versions.
  enum CollectorEndpointVersion {
    // Zipkin API v1, JSON over HTTP.
    // [#comment: The default implementation of Zipkin client before this field is added was only v1
    // and the way user configure this was by not explicitly specifying the version. Consequently,
    // before this is added, the corresponding Zipkin collector expected to receive v1 payload.
    // Hence the motivation of adding HTTP_JSON_V1 as the default is to avoid a breaking change when
    // user upgrading Envoy with this change. Furthermore, we also immediately deprecate this field,
    // since in Zipkin realm this v1 version is considered to be not preferable anymore.]
    DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE = 0
        [deprecated = true, (envoy.annotations.disallowed_by_default_enum) = true];

    // Zipkin API v2, JSON over HTTP.
    HTTP_JSON = 1;

    // Zipkin API v2, protobuf over HTTP.
    HTTP_PROTO = 2;

    // [#not-implemented-hide:]
    GRPC = 3;
  }

  // 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.bootstrap.v3.Bootstrap.StaticResources.clusters>`.
  string collector_cluster = 1 [(validate.rules).string = {min_bytes: 1}];

  // 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.
  string collector_endpoint = 2 [(validate.rules).string = {min_bytes: 1}];

  // 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.
  bool trace_id_128bit = 3;

  // Determines whether client and server spans will share the same span context.
  // The default value is true.
  google.protobuf.BoolValue shared_span_context = 4;

  // Determines the selected collector endpoint version. By default, the ``HTTP_JSON_V1`` will be
  // used.
  CollectorEndpointVersion collector_endpoint_version = 5;
}

// 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]
message DynamicOtConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.trace.v2.DynamicOtConfig";

  // Dynamic library implementing the `OpenTracing API
  // <https://github.com/opentracing/opentracing-cpp>`_.
  string library = 1 [(validate.rules).string = {min_bytes: 1}];

  // The configuration to use when creating a tracer from the given dynamic
  // library.
  google.protobuf.Struct config = 2;
}

// Configuration for the Datadog tracer.
// [#extension: envoy.tracers.datadog]
message DatadogConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.trace.v2.DatadogConfig";

  // The cluster to use for submitting traces to the Datadog agent.
  string collector_cluster = 1 [(validate.rules).string = {min_bytes: 1}];

  // The name used for the service when traces are generated by envoy.
  string service_name = 2 [(validate.rules).string = {min_bytes: 1}];
}

// Configuration for the OpenCensus tracer.
// [#next-free-field: 14]
// [#extension: envoy.tracers.opencensus]
message OpenCensusConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.trace.v2.OpenCensusConfig";

  enum TraceContext {
    // No-op default, no trace context is utilized.
    NONE = 0;

    // W3C Trace-Context format "traceparent:" header.
    TRACE_CONTEXT = 1;

    // Binary "grpc-trace-bin:" header.
    GRPC_TRACE_BIN = 2;

    // "X-Cloud-Trace-Context:" header.
    CLOUD_TRACE_CONTEXT = 3;

    // X-B3-* headers.
    B3 = 4;
  }

  reserved 7;

  // Configures tracing, e.g. the sampler, max number of annotations, etc.
  opencensus.proto.trace.v1.TraceConfig trace_config = 1;

  // Enables the stdout exporter if set to true. This is intended for debugging
  // purposes.
  bool stdout_exporter_enabled = 2;

  // Enables the Stackdriver exporter if set to true. The project_id must also
  // be set.
  bool stackdriver_exporter_enabled = 3;

  // The Cloud project_id to use for Stackdriver tracing.
  string stackdriver_project_id = 4;

  // (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
  string stackdriver_address = 10;

  // (optional) The gRPC server that hosts Stackdriver tracing service. Only
  // Google gRPC is supported. If :ref:`target_uri <envoy_v3_api_field_config.core.v3.GrpcService.GoogleGrpc.target_uri>`
  // is not provided, the default production Stackdriver address will be used.
  core.v3.GrpcService stackdriver_grpc_service = 13;

  // Enables the Zipkin exporter if set to true. The url and service name must
  // also be set.
  bool zipkin_exporter_enabled = 5;

  // The URL to Zipkin, e.g. "http://127.0.0.1:9411/api/v2/spans"
  string zipkin_url = 6;

  // Enables the OpenCensus Agent exporter if set to true. The address must also
  // be set.
  bool ocagent_exporter_enabled = 11;

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

  // List of incoming trace context headers we will accept. First one found
  // wins.
  repeated TraceContext incoming_trace_context = 8;

  // List of outgoing trace context headers we will produce.
  repeated TraceContext outgoing_trace_context = 9;
}

// Configuration structure.
message TraceServiceConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.trace.v2.TraceServiceConfig";

  // The upstream gRPC cluster that hosts the metrics service.
  core.v3.GrpcService grpc_service = 1 [(validate.rules).message = {required: true}];
}