tracer: Add SkyWalking tracer (#13060)

This patch adds a new tracer to support the SkyWalking tracing mechanism and format.

Risk Level: Low, a new extension.
Testing: Unit
Docs Changes: Added
Release Notes: Added

Signed-off-by: wbpcode <[email protected]>

CODEOWNERS

@@ -50,6 +50,8 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/tracers/datadog @cgilmour @palazzem @mattklein123
 # tracers.xray extension
 /*/extensions/tracers/xray @marcomagdy @lavignes @mattklein123
+# tracers.skywalking extension
+/*/extensions/tracers/skywalking @wbpcode @dio @lizan
 # mysql_proxy extension
 /*/extensions/filters/network/mysql_proxy @rshriram @venilnoronha @mattklein123
 # postgres_proxy extension

api/bazel/repositories.bzl

@@ -40,6 +40,10 @@ def api_dependencies():
         name = "com_github_openzipkin_zipkinapi",
         build_file_content = ZIPKINAPI_BUILD_CONTENT,
     )
+    external_http_archive(
+        name = "com_github_apache_skywalking_data_collect_protocol",
+        build_file_content = SKYWALKING_DATA_COLLECT_PROTOCOL_BUILD_CONTENT,
+    )
 
 PROMETHEUSMETRICS_BUILD_CONTENT = """
 load("@envoy_api//bazel:api_build_system.bzl", "api_cc_py_proto_library")
@@ -101,3 +105,30 @@ go_proto_library(
     visibility = ["//visibility:public"],
 )
 """
+
+SKYWALKING_DATA_COLLECT_PROTOCOL_BUILD_CONTENT = """
+load("@rules_proto//proto:defs.bzl", "proto_library")
+load("@rules_cc//cc:defs.bzl", "cc_proto_library")
+load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
+
+proto_library(
+    name = "protocol",
+    srcs = [
+        "common/Common.proto",
+        "language-agent/Tracing.proto",
+    ],
+    visibility = ["//visibility:public"],
+)
+
+cc_proto_library(
+    name = "protocol_cc_proto",
+    deps = [":protocol"],
+    visibility = ["//visibility:public"],
+)
+
+go_proto_library(
+    name = "protocol_go_proto",
+    proto = ":protocol",
+    visibility = ["//visibility:public"],
+)
+"""

api/bazel/repository_locations.bzl

@@ -88,4 +88,15 @@ REPOSITORY_LOCATIONS_SPEC = dict(
         release_date = "2020-08-17",
         use_category = ["api"],
     ),
+    com_github_apache_skywalking_data_collect_protocol = dict(
+        project_name = "SkyWalking API",
+        project_desc = "SkyWalking's language independent model and gRPC API Definitions",
+        project_url = "https://github.com/apache/skywalking-data-collect-protocol",
+        version = "8.1.0",
+        sha256 = "ebea8a6968722524d1bcc4426fb6a29907ddc2902aac7de1559012d3eee90cf9",
+        strip_prefix = "skywalking-data-collect-protocol-{version}",
+        urls = ["https://github.com/apache/skywalking-data-collect-protocol/archive/v{version}.tar.gz"],
+        release_date = "2020-07-29",
+        use_category = ["api"],
+    ),
 )

api/envoy/config/trace/v3/skywalking.proto

@@ -0,0 +1,66 @@
+syntax = "proto3";
+
+package envoy.config.trace.v3;
+
+import "envoy/config/core/v3/grpc_service.proto";
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/sensitive.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 = "SkywalkingProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_migrate).move_to_package =
+    "envoy.extensions.tracers.skywalking.v4alpha";
+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
+// Tracer does not support SkyWalking extension header (``sw8-x``) temporarily.
+// [#extension: envoy.tracers.skywalking]
+message SkyWalkingConfig {
+  // SkyWalking collector service.
+  core.v3.GrpcService grpc_service = 1 [(validate.rules).message = {required: true}];
+
+  ClientConfig client_config = 2;
+}
+
+// Client config for SkyWalking tracer.
+message ClientConfig {
+  // Service name for SkyWalking tracer. If this field is empty, then local service cluster name
+  // that configured by :ref:`Bootstrap node <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.node>`
+  // message's :ref:`cluster <envoy_v3_api_field_config.core.v3.Node.cluster>` field or command line
+  // option :option:`--service-cluster` will be used. If both this field and local service cluster
+  // name are empty, ``EnvoyProxy`` is used as the service name by default.
+  string service_name = 1;
+
+  // Service instance name for SkyWalking tracer. If this field is empty, then local service node
+  // that configured by :ref:`Bootstrap node <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.node>`
+  // message's :ref:`id <envoy_v3_api_field_config.core.v3.Node.id>` field or command line  option
+  // :option:`--service-node` will be used. If both this field and local service node are empty,
+  // ``EnvoyProxy`` is used as the instance name by default.
+  string instance_name = 2;
+
+  // Authentication token config for SkyWalking. SkyWalking can use token authentication to secure
+  // that monitoring application data can be trusted. In current version, Token is considered as a
+  // simple string.
+  // [#comment:TODO(wbpcode): Get backend token through the SDS API.]
+  oneof backend_token_specifier {
+    // Inline authentication token string.
+    string backend_token = 3 [(udpa.annotations.sensitive) = true];
+  }
+
+  // Envoy caches the segment in memory when the SkyWalking backend service is temporarily unavailable.
+  // This field specifies the maximum number of segments that can be cached. If not specified, the
+  // default is 1024.
+  google.protobuf.UInt32Value max_cache_size = 4;
+}

docs/root/start/sandboxes/index.rst

@@ -29,3 +29,4 @@ features. The following sandboxes are available:
     redis
     wasm-cc
     zipkin_tracing
+    skywalking_tracing

docs/root/start/sandboxes/skywalking_tracing.rst

@@ -0,0 +1,89 @@
+.. _install_sandboxes_skywalking_tracing:
+
+SkyWalking Tracing
+==================
+
+The SkyWalking tracing sandbox demonstrates Envoy's :ref:`request tracing <arch_overview_tracing>`
+capabilities using `SkyWalking <http://skywalking.apache.org>`_ as the tracing provider. This sandbox
+is very similar to the Zipkin sandbox. All containers will be deployed inside a virtual network
+called ``envoymesh``.
+
+All incoming requests are routed via the front Envoy, which is acting as a reverse proxy
+sitting on the edge of the ``envoymesh`` network. Port ``8000`` is exposed
+by docker compose (see :repo:`/examples/skywalking-tracing/docker-compose.yaml`). Notice that
+all Envoys are configured to collect request traces (e.g., http_connection_manager/config/tracing setup in
+:repo:`/examples/skywalking-tracing/front-envoy-skywalking.yaml`) and setup to propagate the spans generated
+by the SkyWalking tracer to a SkyWalking cluster (trace driver setup
+in :repo:`/examples/skywalking-tracing/front-envoy-skywalking.yaml`).
+
+When service1 accepts the request forwarded from front envoy, it will make an API call to service2 before
+returning a response.
+
+.. include:: _include/docker-env-setup.rst
+
+Step 3: Build the sandbox
+*************************
+
+To build this sandbox example, and start the example apps run the following commands:
+
+.. code-block:: console
+
+    $ pwd
+    envoy/examples/skywalking-tracing
+    $ docker-compose pull
+    $ docker-compose up --build -d
+    $ docker-compose ps
+
+                Name                              Command                State                                  Ports
+    --------------------------------------------------------------------------------------------------------------------------------------------------
+    skywalking-tracing_elasticsearch_1    /tini -- /usr/local/bin/do ... Up (healthy)   0.0.0.0:9200->9200/tcp, 9300/tcp
+    skywalking-tracing_front-envoy_1      /docker-entrypoint.sh /bin ... Up             10000/tcp, 0.0.0.0:8000->8000/tcp, 0.0.0.0:8001->8001/tcp
+    skywalking-tracing_service1_1         /bin/sh /usr/local/bin/sta ... Up             10000/tcp
+    skywalking-tracing_service2_1         /bin/sh /usr/local/bin/sta ... Up             10000/tcp
+    skywalking-tracing_skywalking-oap_1   bash docker-entrypoint.sh      Up (healthy)   0.0.0.0:11800->11800/tcp, 1234/tcp, 0.0.0.0:12800->12800/tcp
+    skywalking-tracing_skywalking-ui_1    bash docker-entrypoint.sh      Up             0.0.0.0:8080->8080/tcp
+
+Step 4: Generate some load
+**************************
+
+You can now send a request to service1 via the front-envoy as follows:
+
+.. code-block:: console
+
+    $ curl -v localhost:8000/trace/1
+    *   Trying ::1...
+    * TCP_NODELAY set
+    * Connected to localhost (::1) port 8000 (#0)
+    > GET /trace/1 HTTP/1.1
+    > Host: localhost:8000
+    > User-Agent: curl/7.58.0
+    > Accept: */*
+    >
+    < HTTP/1.1 200 OK
+    < content-type: text/html; charset=utf-8
+    < content-length: 89
+    < server: envoy
+    < date: Sat, 10 Oct 2020 01:56:08 GMT
+    < x-envoy-upstream-service-time: 27
+    <
+    Hello from behind Envoy (service 1)! hostname: 1a2ba43d6d84 resolvedhostname: 172.19.0.6
+    * Connection #0 to host localhost left intact
+
+You can get SkyWalking stats of front-envoy after some requests as follows:
+
+.. code-block:: console
+
+    $ curl -s localhost:8001/stats | grep tracing.skywalking
+    tracing.skywalking.cache_flushed: 0
+    tracing.skywalking.segments_dropped: 0
+    tracing.skywalking.segments_flushed: 0
+    tracing.skywalking.segments_sent: 13
+
+Step 5: View the traces in SkyWalking UI
+****************************************
+
+Point your browser to http://localhost:8080 . You should see the SkyWalking dashboard.
+Set the service to "front-envoy" and set the start time to a few minutes before
+the start of the test (step 2) and hit enter. You should see traces from the front-proxy.
+Click on a trace to explore the path taken by the request from front-proxy to service1
+to service2, as well as the latency incurred at each hop.

docs/root/version_history/current.rst

@@ -54,6 +54,7 @@ New Features
 * ratelimit: added :ref:`disable_x_envoy_ratelimited_header <envoy_v3_api_msg_extensions.filters.http.ratelimit.v3.RateLimit>` option to disable `X-Envoy-RateLimited` header.
 * tcp: added a new :ref:`envoy.overload_actions.reject_incoming_connections <config_overload_manager_overload_actions>` action to reject incoming TCP connections.
 * tls: added support for RSA certificates with 4096-bit keys in FIPS mode.
+* tracing: added SkyWalking tracer.
 * xds: added support for resource TTLs. A TTL is specified on the :ref:`Resource <envoy_api_msg_Resource>`. For SotW, a :ref:`Resource <envoy_api_msg_Resource>` can be embedded
   in the list of resources to specify the TTL.
 

examples/front-proxy/service.py

@@ -19,7 +19,10 @@
     'X-B3-Flags',
 
     # Jaeger header (for native client)
-    "uber-trace-id"
+    "uber-trace-id",
+
+    # SkyWalking headers.
+    "sw8"
 ]
 
 

examples/skywalking-tracing/Dockerfile-frontenvoy

@@ -0,0 +1,7 @@
+FROM envoyproxy/envoy-dev:latest
+
+RUN apt-get update && apt-get -q install -y \
+    curl
+COPY ./front-envoy-skywalking.yaml /etc/front-envoy.yaml
+RUN chmod go+r /etc/front-envoy.yaml
+CMD /usr/local/bin/envoy -c /etc/front-envoy.yaml --service-cluster front-proxy

examples/skywalking-tracing/README.md

@@ -0,0 +1,2 @@
+To learn about this sandbox and for instructions on how to run it please head over
+to the [envoy docs](https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/skywalking_tracing)