tracing: introduce spawn_upstream_span in the tracing config (#29659)

* tracing: introduce spawn_upstream_span in the tracing config

Signed-off-by: wbpcode <wangbaiping@corp.netease.com>

* optimize docs

Signed-off-by: wbpcode <wangbaiping@corp.netease.com>

---------

Signed-off-by: wbpcode <wangbaiping@corp.netease.com>

Mirrored from https://github.com/envoyproxy/envoy @ 16b71f85ed6de7a091e530996381b62ba7adb32e

envoy/config/trace/v3/skywalking.proto

@@ -22,9 +22,9 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // [#protodoc-title: SkyWalking tracer]
 
 // Configuration for the SkyWalking tracer. Please note that if SkyWalking tracer is used as the
-// provider of http tracer, then
-// :ref:`start_child_span <envoy_v3_api_field_extensions.filters.http.router.v3.Router.start_child_span>`
-// in the router must be set to true to get the correct topology and tracing data. Moreover, SkyWalking
+// provider of tracing, then
+// :ref:`spawn_upstream_span <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.spawn_upstream_span>`
+// in the tracing config must be set to true to get the correct topology and tracing data. Moreover, SkyWalking
 // Tracer does not support SkyWalking extension header (``sw8-x``) temporarily.
 // [#extension: envoy.tracers.skywalking]
 message SkyWalkingConfig {

envoy/extensions/filters/http/router/v3/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/config/accesslog/v3:pkg",
         "//envoy/extensions/filters/network/http_connection_manager/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",

envoy/extensions/filters/http/router/v3/router.proto

@@ -8,6 +8,7 @@ import "envoy/extensions/filters/network/http_connection_manager/v3/http_connect
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -52,7 +53,13 @@ message Router {
   // useful in scenarios where other filters (auth, ratelimit, etc.) make
   // outbound calls and have child spans rooted at the same ingress
   // parent. Defaults to false.
-  bool start_child_span = 2;
+  //
+  // .. attention::
+  //   This field is 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 start_child_span = 2
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Configuration for HTTP upstream logs emitted by the router. Upstream logs
   // are configured in the same way as access logs, but each log entry represents

envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto

@@ -130,7 +130,7 @@ message HttpConnectionManager {
     UNESCAPE_AND_FORWARD = 4;
   }
 
-  // [#next-free-field: 10]
+  // [#next-free-field: 11]
   message Tracing {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing";
@@ -195,6 +195,27 @@ message HttpConnectionManager {
     //   Such a constraint is inherent to OpenCensus itself. It cannot be overcome without changes
     //   on OpenCensus side.
     config.trace.v3.Tracing.Http provider = 9;
+
+    // Create separate tracing span for each upstream request if true. And if this flag is set to true,
+    // the tracing provider will assume that Envoy will be independent hop in the trace chain and may
+    // set span type to client or server based on this flag.
+    // This will deprecate the
+    // :ref:`start_child_span <envoy_v3_api_field_extensions.filters.http.router.v3.Router.start_child_span>`
+    // in the router.
+    //
+    // Users should set appropriate value based on their tracing provider and actual scenario:
+    //
+    // * If Envoy is used as sidecar and users want to make the sidecar and its application as only one
+    //   hop in the trace chain, this flag should be set to false. And please also make sure the
+    //   :ref:`start_child_span <envoy_v3_api_field_extensions.filters.http.router.v3.Router.start_child_span>`
+    //   in the router is not set to true.
+    // * If Envoy is used as gateway or independent proxy, or users want to make the sidecar and its
+    //   application as different hops in the trace chain, this flag should be set to true.
+    // * If tracing provider that has explicit requirements on span creation (like SkyWalking),
+    //   this flag should be set to true.
+    //
+    // The default value is false for now for backward compatibility.
+    google.protobuf.BoolValue spawn_upstream_span = 10;
   }
 
   message InternalAddressConfig {