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

syntax = "proto3";

package envoy.config.trace.v3;

import "google/protobuf/wrappers.proto";

import "envoy/annotations/deprecation.proto";
import "udpa/annotations/migrate.proto";
import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.config.trace.v3";
option java_outer_classname = "ZipkinProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/trace/v3;tracev3";
option (udpa.annotations.file_migrate).move_to_package = "envoy.extensions.tracers.zipkin.v4alpha";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Zipkin tracer]

// Configuration for the Zipkin tracer.
// [#extension: envoy.tracers.zipkin]
// [#next-free-field: 8]
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.
  string collector_cluster = 1 [(validate.rules).string = {min_len: 1}];

  // The API endpoint of the Zipkin service where the spans will be sent. When
  // using a standard Zipkin installation.
  string collector_endpoint = 2 [(validate.rules).string = {min_len: 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.
  CollectorEndpointVersion collector_endpoint_version = 5;

  // Optional hostname to use when sending spans to the collector_cluster. Useful for collectors
  // that require a specific hostname. Defaults to :ref:`collector_cluster <envoy_v3_api_field_config.trace.v3.ZipkinConfig.collector_cluster>` above.
  string collector_hostname = 6;

  // If this is set to true, then Envoy will be treated as an independent hop in trace chain. A complete span pair will be created for a single
  // request. Server span will be created for the downstream request and client span will be created for the related upstream request.
  // This should be set to true in the following cases:
  //
  // * The Envoy Proxy is used as gateway or ingress.
  // * The Envoy Proxy is used as sidecar but inbound traffic capturing or outbound traffic capturing is disabled.
  // * Any case that the `start_child_span of router <envoy_v3_api_field_extensions.filters.http.router.v3.Router.start_child_span>` is set to true.
  //
  // .. attention::
  //
  //   If this is set to true, then the
  //   :ref:`start_child_span of router <envoy_v3_api_field_extensions.filters.http.router.v3.Router.start_child_span>`
  //   SHOULD be set to true also to ensure the correctness of trace chain.
  bool split_spans_for_request = 7;
}