From 8a1d99a8b2b9e0e70ba59b29e857f2eda610cacd Mon Sep 17 00:00:00 2001 From: "data-plane-api(CircleCI)" Date: Tue, 3 Dec 2019 16:11:40 +0000 Subject: [PATCH] tracing: enhance custom tags source (#8279) Signed-off-by: Yi Tang Mirrored from https://github.com/envoyproxy/envoy @ 222890cbff2f9d7dff74fca6535771c063104d68 --- docs/BUILD | 2 + envoy/api/v2/core/base.proto | 1 + envoy/api/v2/route/BUILD | 1 + envoy/api/v2/route/route.proto | 9 ++ envoy/api/v3alpha/core/base.proto | 1 + envoy/api/v3alpha/route/BUILD | 1 + envoy/api/v3alpha/route/route.proto | 9 ++ .../network/http_connection_manager/v2/BUILD | 1 + .../v2/http_connection_manager.proto | 12 ++- .../http_connection_manager/v3alpha/BUILD | 1 + .../v3alpha/http_connection_manager.proto | 15 ++- envoy/type/metadata/v2/BUILD | 7 ++ envoy/type/metadata/v2/metadata.proto | 95 +++++++++++++++++++ envoy/type/tracing/v2/BUILD | 9 ++ envoy/type/tracing/v2/custom_tag.proto | 83 ++++++++++++++++ 15 files changed, 237 insertions(+), 10 deletions(-) create mode 100644 envoy/type/metadata/v2/BUILD create mode 100644 envoy/type/metadata/v2/metadata.proto create mode 100644 envoy/type/tracing/v2/BUILD create mode 100644 envoy/type/tracing/v2/custom_tag.proto diff --git a/docs/BUILD b/docs/BUILD index 57e0d60c..bd989fee 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -93,5 +93,7 @@ proto_library( "//envoy/service/trace/v2:pkg", "//envoy/type:pkg", "//envoy/type/matcher:pkg", + "//envoy/type/metadata/v2:pkg", + "//envoy/type/tracing/v2:pkg", ], ) diff --git a/envoy/api/v2/core/base.proto b/envoy/api/v2/core/base.proto index e5299cb4..ccf2ea61 100644 --- a/envoy/api/v2/core/base.proto +++ b/envoy/api/v2/core/base.proto @@ -136,6 +136,7 @@ message Node { // * ``{"envoy.lb": {"canary": }}`` This indicates the canary status of an // endpoint and is also used during header processing // (x-envoy-upstream-canary) and for stats purposes. +// [#next-major-version: move to type/metadata/v2] message Metadata { // Key is the reverse DNS filter name, e.g. com.acme.widget. The envoy.* // namespace is reserved for Envoy's built-in filters. diff --git a/envoy/api/v2/route/BUILD b/envoy/api/v2/route/BUILD index d3b85c4c..776207ac 100644 --- a/envoy/api/v2/route/BUILD +++ b/envoy/api/v2/route/BUILD @@ -9,5 +9,6 @@ api_proto_package( "//envoy/api/v2/core:pkg", "//envoy/type:pkg", "//envoy/type/matcher:pkg", + "//envoy/type/tracing/v2:pkg", ], ) diff --git a/envoy/api/v2/route/route.proto b/envoy/api/v2/route/route.proto index 2810664e..df418d49 100644 --- a/envoy/api/v2/route/route.proto +++ b/envoy/api/v2/route/route.proto @@ -11,6 +11,7 @@ import "envoy/type/matcher/regex.proto"; import "envoy/type/matcher/string.proto"; import "envoy/type/percent.proto"; import "envoy/type/range.proto"; +import "envoy/type/tracing/v2/custom_tag.proto"; import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; @@ -1100,6 +1101,14 @@ message Tracing { // :ref:`HTTP Connection Manager `. // Default: 100% type.FractionalPercent overall_sampling = 3; + + // A list of custom tags with unique tag name to create tags for the active span. + // It will take effect after merging with the :ref:`corresponding configuration + // ` + // configured in the HTTP connection manager. If two tags with the same name are configured + // each in the HTTP connection manager and the route level, the one configured here takes + // priority. + repeated type.tracing.v2.CustomTag custom_tags = 4; } // A virtual cluster is a way of specifying a regex matching rule against diff --git a/envoy/api/v3alpha/core/base.proto b/envoy/api/v3alpha/core/base.proto index 46e19896..631a2605 100644 --- a/envoy/api/v3alpha/core/base.proto +++ b/envoy/api/v3alpha/core/base.proto @@ -143,6 +143,7 @@ message Node { // * ``{"envoy.lb": {"canary": }}`` This indicates the canary status of an // endpoint and is also used during header processing // (x-envoy-upstream-canary) and for stats purposes. +// [#next-major-version: move to type/metadata/v2] message Metadata { option (udpa.api.annotations.versioning).previous_message_type = "envoy.api.v2.core.Metadata"; diff --git a/envoy/api/v3alpha/route/BUILD b/envoy/api/v3alpha/route/BUILD index c8e4619a..d4850e8a 100644 --- a/envoy/api/v3alpha/route/BUILD +++ b/envoy/api/v3alpha/route/BUILD @@ -8,6 +8,7 @@ api_proto_package( deps = [ "//envoy/api/v3alpha/core:pkg", "//envoy/type/matcher/v3alpha:pkg", + "//envoy/type/tracing/v2:pkg", "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/api/annotations:pkg", ], diff --git a/envoy/api/v3alpha/route/route.proto b/envoy/api/v3alpha/route/route.proto index 87987dca..82f7e0dc 100644 --- a/envoy/api/v3alpha/route/route.proto +++ b/envoy/api/v3alpha/route/route.proto @@ -9,6 +9,7 @@ option java_package = "io.envoyproxy.envoy.api.v3alpha.route"; import "envoy/api/v3alpha/core/base.proto"; import "envoy/type/matcher/v3alpha/regex.proto"; import "envoy/type/matcher/v3alpha/string.proto"; +import "envoy/type/tracing/v2/custom_tag.proto"; import "envoy/type/v3alpha/percent.proto"; import "envoy/type/v3alpha/range.proto"; @@ -1112,6 +1113,14 @@ message Tracing { // :ref:`HTTP Connection Manager `. // Default: 100% type.v3alpha.FractionalPercent overall_sampling = 3; + + // A list of custom tags with unique tag name to create tags for the active span. + // It will take effect after merging with the :ref:`corresponding configuration + // ` + // configured in the HTTP connection manager. If two tags with the same name are configured + // each in the HTTP connection manager and the route level, the one configured here takes + // priority. + repeated type.tracing.v2.CustomTag custom_tags = 4; } // A virtual cluster is a way of specifying a regex matching rule against diff --git a/envoy/config/filter/network/http_connection_manager/v2/BUILD b/envoy/config/filter/network/http_connection_manager/v2/BUILD index a9f3622d..3984f8d7 100644 --- a/envoy/config/filter/network/http_connection_manager/v2/BUILD +++ b/envoy/config/filter/network/http_connection_manager/v2/BUILD @@ -10,5 +10,6 @@ api_proto_package( "//envoy/api/v2/core:pkg", "//envoy/config/filter/accesslog/v2:pkg", "//envoy/type:pkg", + "//envoy/type/tracing/v2:pkg", ], ) diff --git a/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto b/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto index 5a826725..2f44713b 100644 --- a/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto +++ b/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto @@ -12,6 +12,7 @@ import "envoy/api/v2/rds.proto"; import "envoy/api/v2/srds.proto"; import "envoy/config/filter/accesslog/v2/accesslog.proto"; import "envoy/type/percent.proto"; +import "envoy/type/tracing/v2/custom_tag.proto"; import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; @@ -84,7 +85,7 @@ message HttpConnectionManager { ALWAYS_FORWARD_ONLY = 4; } - // [#next-free-field: 8] + // [#next-free-field: 9] message Tracing { enum OperationName { // The HTTP listener is used for ingress/incoming requests. @@ -106,7 +107,11 @@ message HttpConnectionManager { // A list of header names used to create tags for the active span. The header name is used to // populate the tag name, and the header value is used to populate the tag value. The tag is // created if the specified header name is present in the request's headers. - repeated string request_headers_for_tags = 2; + // + // .. attention:: + // This field has been deprecated in favor of :ref:`custom_tags + // `. + repeated string request_headers_for_tags = 2 [deprecated = true]; // Target percentage of requests managed by this HTTP connection manager that will be force // traced if the :ref:`x-client-trace-id ` @@ -141,6 +146,9 @@ message HttpConnectionManager { // truncate lengthy request paths to meet the needs of a tracing backend. // Default: 256 google.protobuf.UInt32Value max_path_tag_length = 7; + + // A list of custom tags with unique tag name to create tags for the active span. + repeated type.tracing.v2.CustomTag custom_tags = 8; } message InternalAddressConfig { diff --git a/envoy/config/filter/network/http_connection_manager/v3alpha/BUILD b/envoy/config/filter/network/http_connection_manager/v3alpha/BUILD index f0ce7045..2af4ce50 100644 --- a/envoy/config/filter/network/http_connection_manager/v3alpha/BUILD +++ b/envoy/config/filter/network/http_connection_manager/v3alpha/BUILD @@ -9,6 +9,7 @@ api_proto_package( "//envoy/api/v3alpha:pkg", "//envoy/api/v3alpha/core:pkg", "//envoy/config/filter/accesslog/v3alpha:pkg", + "//envoy/type/tracing/v2:pkg", "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/api/annotations:pkg", ], diff --git a/envoy/config/filter/network/http_connection_manager/v3alpha/http_connection_manager.proto b/envoy/config/filter/network/http_connection_manager/v3alpha/http_connection_manager.proto index 1c534d1e..9dfb6263 100644 --- a/envoy/config/filter/network/http_connection_manager/v3alpha/http_connection_manager.proto +++ b/envoy/config/filter/network/http_connection_manager/v3alpha/http_connection_manager.proto @@ -11,6 +11,7 @@ import "envoy/api/v3alpha/core/protocol.proto"; import "envoy/api/v3alpha/rds.proto"; import "envoy/api/v3alpha/srds.proto"; import "envoy/config/filter/accesslog/v3alpha/accesslog.proto"; +import "envoy/type/tracing/v2/custom_tag.proto"; import "envoy/type/v3alpha/percent.proto"; import "google/protobuf/any.proto"; @@ -89,7 +90,7 @@ message HttpConnectionManager { ALWAYS_FORWARD_ONLY = 4; } - // [#next-free-field: 8] + // [#next-free-field: 9] message Tracing { option (udpa.api.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing"; @@ -102,14 +103,9 @@ message HttpConnectionManager { EGRESS = 1; } - reserved 1; + reserved 1, 2; - reserved "operation_name"; - - // A list of header names used to create tags for the active span. The header name is used to - // populate the tag name, and the header value is used to populate the tag value. The tag is - // created if the specified header name is present in the request's headers. - repeated string request_headers_for_tags = 2; + reserved "operation_name", "request_headers_for_tags"; // Target percentage of requests managed by this HTTP connection manager that will be force // traced if the :ref:`x-client-trace-id ` @@ -144,6 +140,9 @@ message HttpConnectionManager { // truncate lengthy request paths to meet the needs of a tracing backend. // Default: 256 google.protobuf.UInt32Value max_path_tag_length = 7; + + // A list of custom tags with unique tag name to create tags for the active span. + repeated type.tracing.v2.CustomTag custom_tags = 8; } message InternalAddressConfig { diff --git a/envoy/type/metadata/v2/BUILD b/envoy/type/metadata/v2/BUILD new file mode 100644 index 00000000..5dc095ad --- /dev/null +++ b/envoy/type/metadata/v2/BUILD @@ -0,0 +1,7 @@ +# DO NOT EDIT. This file is generated by tools/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package() diff --git a/envoy/type/metadata/v2/metadata.proto b/envoy/type/metadata/v2/metadata.proto new file mode 100644 index 00000000..ac51fe41 --- /dev/null +++ b/envoy/type/metadata/v2/metadata.proto @@ -0,0 +1,95 @@ +syntax = "proto3"; + +package envoy.type.metadata.v2; + +option java_outer_classname = "MetadataProto"; +option java_multiple_files = true; +option java_package = "io.envoyproxy.envoy.type.metadata.v2"; + +import "validate/validate.proto"; + +// [#protodoc-title: Metadata] + +// MetadataKey provides a general interface using `key` and `path` to retrieve value from +// :ref:`Metadata `. +// +// For example, for the following Metadata: +// +// .. code-block:: yaml +// +// filter_metadata: +// envoy.xxx: +// prop: +// foo: bar +// xyz: +// hello: envoy +// +// The following MetadataKey will retrieve a string value "bar" from the Metadata. +// +// .. code-block:: yaml +// +// key: envoy.xxx +// path: +// - key: prop +// - key: foo +// +message MetadataKey { + // Specifies the segment in a path to retrieve value from Metadata. + // Currently it is only supported to specify the key, i.e. field name, as one segment of a path. + message PathSegment { + oneof segment { + option (validate.required) = true; + + // If specified, use the key to retrieve the value in a Struct. + string key = 1 [(validate.rules).string = {min_bytes: 1}]; + } + } + + // The key name of Metadata to retrieve the Struct from the metadata. + // Typically, it represents a builtin subsystem or custom extension. + string key = 1 [(validate.rules).string = {min_bytes: 1}]; + + // The path to retrieve the Value from the Struct. It can be a prefix or a full path, + // e.g. ``[prop, xyz]`` for a struct or ``[prop, foo]`` for a string in the example, + // which depends on the particular scenario. + // + // Note: Due to that only the key type segment is supported, the path can not specify a list + // unless the list is the last segment. + repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}]; +} + +// Describes what kind of metadata. +message MetadataKind { + // Represents dynamic metadata associated with the request. + message Request { + } + + // Represents metadata from :ref:`the route`. + message Route { + } + + // Represents metadata from :ref:`the upstream cluster`. + message Cluster { + } + + // Represents metadata from :ref:`the upstream + // host`. + message Host { + } + + oneof kind { + option (validate.required) = true; + + // Request kind of metadata. + Request request = 1; + + // Route kind of metadata. + Route route = 2; + + // Cluster kind of metadata. + Cluster cluster = 3; + + // Host kind of metadata. + Host host = 4; + } +} diff --git a/envoy/type/tracing/v2/BUILD b/envoy/type/tracing/v2/BUILD new file mode 100644 index 00000000..7088ddfe --- /dev/null +++ b/envoy/type/tracing/v2/BUILD @@ -0,0 +1,9 @@ +# DO NOT EDIT. This file is generated by tools/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package( + deps = ["//envoy/type/metadata/v2:pkg"], +) diff --git a/envoy/type/tracing/v2/custom_tag.proto b/envoy/type/tracing/v2/custom_tag.proto new file mode 100644 index 00000000..555a198d --- /dev/null +++ b/envoy/type/tracing/v2/custom_tag.proto @@ -0,0 +1,83 @@ +syntax = "proto3"; + +package envoy.type.tracing.v2; + +option java_outer_classname = "CustomTagProto"; +option java_multiple_files = true; +option java_package = "io.envoyproxy.envoy.type.tracing.v2"; + +import "envoy/type/metadata/v2/metadata.proto"; + +import "validate/validate.proto"; + +// [#protodoc-title: Custom Tag] + +// Describes custom tags for the active span. +// [#next-free-field: 6] +message CustomTag { + // Literal type custom tag with static value for the tag value. + message Literal { + // Static literal value to populate the tag value. + string value = 1 [(validate.rules).string = {min_bytes: 1}]; + } + + // Environment type custom tag with environment name and default value. + message Environment { + // Environment variable name to obtain the value to populate the tag value. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // When the environment variable is not found, + // the tag value will be populated with this default value if specified, + // otherwise no tag will be populated. + string default_value = 2; + } + + // Header type custom tag with header name and default value. + message Header { + // Header name to obtain the value to populate the tag value. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // When the header does not exist, + // the tag value will be populated with this default value if specified, + // otherwise no tag will be populated. + string default_value = 2; + } + + // Metadata type custom tag using + // :ref:`MetadataKey ` to retrieve the protobuf value + // from :ref:`Metadata `, and populate the tag value with + // `the canonical JSON `_ + // representation of it. + message Metadata { + // Specify what kind of metadata to obtain tag value from. + metadata.v2.MetadataKind kind = 1; + + // Metadata key to define the path to retrieve the tag value. + metadata.v2.MetadataKey metadata_key = 2; + + // When no valid metadata is found, + // the tag value would be populated with this default value if specified, + // otherwise no tag would be populated. + string default_value = 3; + } + + // Used to populate the tag name. + string tag = 1 [(validate.rules).string = {min_bytes: 1}]; + + // Used to specify what kind of custom tag. + oneof type { + option (validate.required) = true; + + // A literal custom tag. + Literal literal = 2; + + // An environment custom tag. + Environment environment = 3; + + // A request header custom tag. + Header request_header = 4; + + // A custom tag to obtain tag value from the metadata. + Metadata metadata = 5; + } +}