syntax = "proto3";

package envoy.config.trace.v3;

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

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";

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

  // Available trace context options for handling different trace header formats.
  enum TraceContextOption {
    // Use B3 headers only (default behavior).
    USE_B3 = 0;

    // Enable B3 and W3C dual header support:
    // - For downstream: Extract from B3 headers first, fallback to W3C traceparent if B3 is unavailable.
    // - For upstream: Inject both B3 and W3C traceparent headers.
    // When this option is NOT set, only B3 headers are used for both extraction and injection.
    USE_B3_WITH_W3C_PROPAGATION = 1;
  }

  // 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::
  //     This field will be deprecated in future releases in favor of
  //     :ref:`collector_service <envoy_v3_api_field_config.trace.v3.ZipkinConfig.collector_service>`.
  //
  //     Either this field or ``collector_service`` must be specified.
  string collector_cluster = 1;

  // The API endpoint of the Zipkin service where the spans will be sent. When
  // using a standard Zipkin installation.
  //
  // .. note::
  //     This field will be deprecated in future releases in favor of
  //     :ref:`collector_service <envoy_v3_api_field_config.trace.v3.ZipkinConfig.collector_service>`.
  //
  //     Required when using ``collector_cluster``.
  string collector_endpoint = 2;

  // 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.
  //
  // .. note::
  //     This field will be deprecated in future releases in favor of
  //     :ref:`collector_service <envoy_v3_api_field_config.trace.v3.ZipkinConfig.collector_service>`.
  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 :ref:`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.
  //
  //   Both this field and ``start_child_span`` are deprecated by the
  //   :ref:`spawn_upstream_span <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.spawn_upstream_span>`.
  //   Please use that ``spawn_upstream_span`` field to control the span creation.
  bool split_spans_for_request = 7
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

  // Determines which trace context format to use for trace header extraction and propagation.
  // This controls both downstream request header extraction and upstream request header injection.
  // Here is the spec for W3C trace headers: https://www.w3.org/TR/trace-context/
  // The default value is USE_B3 to maintain backward compatibility.
  TraceContextOption trace_context_option = 8;

  // HTTP service configuration for the Zipkin collector.
  // When specified, this configuration takes precedence over the legacy fields:
  // collector_cluster, collector_endpoint, and collector_hostname.
  // This provides a complete HTTP service configuration including cluster, URI, timeout, and headers.
  // If not specified, the legacy fields above will be used for backward compatibility.
  //
  // Required fields when using collector_service:
  //
  // * ``http_uri.cluster`` - Must be specified and non-empty
  // * ``http_uri.uri`` - Must be specified and non-empty
  // * ``http_uri.timeout`` - Optional
  //
  // Full URI Support with Automatic Parsing:
  //
  // The ``uri`` field supports both path-only and full URI formats:
  //
  // .. code-block:: yaml
  //
  //   tracing:
  //     provider:
  //       name: envoy.tracers.zipkin
  //       typed_config:
  //         "@type": type.googleapis.com/envoy.config.trace.v3.ZipkinConfig
  //         collector_service:
  //           http_uri:
  //             # Full URI format - hostname and path are extracted automatically
  //             uri: "https://zipkin-collector.example.com/api/v2/spans"
  //             cluster: zipkin
  //             timeout: 5s
  //           request_headers_to_add:
  //             - header:
  //                 key: "X-Custom-Token"
  //                 value: "your-custom-token"
  //             - header:
  //                 key: "X-Service-ID"
  //                 value: "your-service-id"
  //
  // URI Parsing Behavior:
  //
  // * Full URI: ``"https://zipkin-collector.example.com/api/v2/spans"``
  //
  //   * Hostname: ``zipkin-collector.example.com`` (sets HTTP ``Host`` header)
  //   * Path: ``/api/v2/spans`` (sets HTTP request path)
  //
  // * Path only: ``"/api/v2/spans"``
  //
  //   * Hostname: Uses cluster name as fallback
  //   * Path: ``/api/v2/spans``
  core.v3.HttpService collector_service = 9;

  // Determines whether trace IDs will include a timestamp in the first 4 bytes.
  // When enabled, trace IDs are generated with the format: [32-bit epoch seconds][32-bit random].
  // The default value is false, which results in fully random trace IDs.
  // For 128-bit trace IDs, the timestamp is encoded in the high 32 bits of the high 64-bit word.
  bool timestamp_trace_ids = 10;
}
