api: extract tracing protos from bootstrap (#342)

Signed-off-by: Taiki Ono <taiks.4559@gmail.com>

api/BUILD

@@ -29,6 +29,7 @@ api_proto_library(
         ":lds",
         ":sds",
         ":stats",
+        ":trace",
     ],
 )
 
@@ -144,6 +145,11 @@ api_proto_library(
     ],
 )
 
+api_proto_library(
+    name = "trace",
+    srcs = ["trace.proto"],
+)
+
 # TODO(htuch): Grow this to cover everything we want to generate docs for, so we can just invoke
 # bazel build //api --aspects tools/protodoc/protodoc.bzl%proto_doc_aspect  --output_groups=rst
 proto_library(

api/bootstrap.proto

@@ -13,10 +13,9 @@ import "api/cds.proto";
 import "api/lds.proto";
 import "api/sds.proto";
 import "api/stats.proto";
+import "api/trace.proto";
 
 import "google/protobuf/duration.proto";
-import "google/protobuf/struct.proto";
-import "google/protobuf/wrappers.proto";
 
 import "validate/validate.proto";
 import "gogoproto/gogo.proto";
@@ -116,50 +115,6 @@ message Bootstrap {
   Admin admin = 12 [(validate.rules).message.required = true, (gogoproto.nullable) = false];
 }
 
-// Configuration for the LightStep tracer.
-message 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
-  // <http://lightstep.com/>`_ API.
-  string access_token_file = 2 [(validate.rules).string.min_bytes = 1];
-}
-
-message ZipkinConfig {
-  // 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_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];
-}
-
-// The :ref:`tracing <arch_overview_tracing>` configuration specifies global
-// settings for the HTTP tracer used by Envoy. The configuration is defined by
-// the :ref:`Bootstrap <envoy_api_msg_Bootstrap>` :ref:`tracing
-// <envoy_api_field_Bootstrap.tracing>` field. Envoy may support other tracers
-// in the future, but right now the HTTP tracer is the only one supported.
-message Tracing {
-  message Http {
-    // The name of the HTTP trace driver to instantiate. The name must match a
-    // supported HTTP trace driver. *envoy.lightstep* and *envoy.zipkin* are
-    // built-in trace drivers.
-    string name = 1 [(validate.rules).string.min_bytes = 1];
-
-    // Trace driver specific configuration which depends on the driver being
-    // instantiated. See the :ref:`LightstepConfig
-    // <envoy_api_msg_LightstepConfig>` and :ref:`ZipkinConfig
-    // <envoy_api_msg_ZipkinConfig>` trace drivers for examples.
-    google.protobuf.Struct config = 2;
-  }
-  // Provides configuration for the HTTP tracer.
-  Http http = 1;
-}
-
 // Administration interface :ref:`operations documentation
 // <operations_admin_interface>`.
 message Admin {

api/stats.proto

@@ -1,5 +1,5 @@
 // [#protodoc-title: Stats]
-// Protos for stats related messages.
+// Statistics :ref:`architecture overview <arch_overview_statistics>`.
 
 syntax = "proto3";
 
@@ -28,7 +28,7 @@ message StatsSink {
   google.protobuf.Struct config = 2;
 }
 
-// Statistics :ref:`architecture overview <arch_overview_statistics>`.
+// Statistics configuration such as tagging.
 message StatsConfig {
   // Each stat name is iteratively processed through these tag specifiers.
   // When a tag is matched, the first capture group is removed from the name so

api/trace.proto

@@ -0,0 +1,54 @@
+// [#protodoc-title: Tracing]
+// Tracing :ref:`architecture overview <arch_overview_tracing>`.
+
+syntax = "proto3";
+
+package envoy.api.v2;
+
+import "google/protobuf/struct.proto";
+
+import "validate/validate.proto";
+
+// The tracing configuration specifies global
+// settings for the HTTP tracer used by Envoy. The configuration is defined by
+// the :ref:`Bootstrap <envoy_api_msg_Bootstrap>` :ref:`tracing
+// <envoy_api_field_Bootstrap.tracing>` field. Envoy may support other tracers
+// in the future, but right now the HTTP tracer is the only one supported.
+message Tracing {
+  message Http {
+    // The name of the HTTP trace driver to instantiate. The name must match a
+    // supported HTTP trace driver. *envoy.lightstep* and *envoy.zipkin* are
+    // built-in trace drivers.
+    string name = 1 [(validate.rules).string.min_bytes = 1];
+
+    // Trace driver specific configuration which depends on the driver being
+    // instantiated. See the :ref:`LightstepConfig
+    // <envoy_api_msg_LightstepConfig>` and :ref:`ZipkinConfig
+    // <envoy_api_msg_ZipkinConfig>` trace drivers for examples.
+    google.protobuf.Struct config = 2;
+  }
+  // Provides configuration for the HTTP tracer.
+  Http http = 1;
+}
+
+// Configuration for the LightStep tracer.
+message 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
+  // <http://lightstep.com/>`_ API.
+  string access_token_file = 2 [(validate.rules).string.min_bytes = 1];
+}
+
+message ZipkinConfig {
+  // 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_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];
+}

docs/build.sh

@@ -38,6 +38,7 @@ PROTO_RST="
   /api/rls/api/rls.proto.rst
   /api/sds/api/sds.proto.rst
   /api/stats/api/stats.proto.rst
+  /api/trace/api/trace.proto.rst
   /api/filter/accesslog/accesslog/api/filter/accesslog/accesslog.proto.rst
   /api/filter/fault/api/filter/fault.proto.rst
   /api/filter/http/buffer/api/filter/http/buffer.proto.rst

docs/root/api-v2/api.rst

@@ -15,6 +15,7 @@ v2 API reference
   rds.proto
   sds.proto
   stats.proto
+  trace.proto
   base.proto
   address.proto
   protocol.proto