feat: add support for tracing tags

api/v1alpha1/shared_types.go

@@ -863,6 +863,8 @@ type Tracing struct {
 	// CustomTags defines the custom tags to add to each span.
 	// If provider is kubernetes, pod name and namespace are added by default.
 	//
+	// Deprecated: Use Tags instead.
+	//
 	// +optional
 	CustomTags map[string]CustomTag `json:"customTags,omitempty"`
 	// Tags defines the custom tags to add to each span.

charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml

@@ -2418,6 +2418,8 @@ spec:
                         description: |-
                           CustomTags defines the custom tags to add to each span.
                           If provider is kubernetes, pod name and namespace are added by default.
+
+                          Deprecated: Use Tags instead.
                         type: object
                       samplingFraction:
                         description: |-

charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml

@@ -15045,6 +15045,8 @@ spec:
                         description: |-
                           CustomTags defines the custom tags to add to each span.
                           If provider is kubernetes, pod name and namespace are added by default.
+
+                          Deprecated: Use Tags instead.
                         type: object
                       provider:
                         description: Provider defines the tracing provider.

charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml

@@ -2417,6 +2417,8 @@ spec:
                         description: |-
                           CustomTags defines the custom tags to add to each span.
                           If provider is kubernetes, pod name and namespace are added by default.
+
+                          Deprecated: Use Tags instead.
                         type: object
                       samplingFraction:
                         description: |-

charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml

@@ -15044,6 +15044,8 @@ spec:
                         description: |-
                           CustomTags defines the custom tags to add to each span.
                           If provider is kubernetes, pod name and namespace are added by default.
+
+                          Deprecated: Use Tags instead.
                         type: object
                       provider:
                         description: Provider defines the tracing provider.

internal/gatewayapi/listener.go

@@ -786,6 +786,7 @@ func (t *Translator) processTracing(gw *gwapiv1.Gateway, envoyproxy *egv1a1.Envo
 		ServiceName:  serviceName,
 		SamplingRate: proxySamplingRate(tracing),
 		CustomTags:   tracing.CustomTags,
+		Tags:         tracing.Tags,
 		Destination: ir.RouteDestination{
 			Name:     destName,
 			Settings: ds,

internal/ir/xds.go

@@ -2599,6 +2599,7 @@ type Tracing struct {
 	Authority    string                      `json:"authority,omitempty"`
 	SamplingRate float64                     `json:"samplingRate,omitempty"`
 	CustomTags   map[string]egv1a1.CustomTag `json:"customTags,omitempty"`
+	Tags         map[string]string           `json:"tags,omitempty"`
 	Destination  RouteDestination            `json:"destination,omitempty"`
 	Traffic      *TrafficFeatures            `json:"traffic,omitempty"`
 	Provider     egv1a1.TracingProvider      `json:"provider"`

internal/xds/translator/route.go

@@ -818,7 +818,7 @@ func buildRouteTracing(httpRoute *ir.HTTPRoute) (*routev3.Tracing, error) {
 	}
 
 	tracing := httpRoute.Traffic.Telemetry.Tracing
-	tags, err := buildTracingTags(tracing.CustomTags)
+	tags, err := buildTracingTags(tracing.CustomTags, tracing.Tags)
 	if err != nil {
 		return nil, fmt.Errorf("failed to build route tracing tags:%w", err)
 	}

internal/xds/translator/tracing.go

@@ -93,7 +93,7 @@ func buildHCMTracing(tracing *ir.Tracing) (*hcm.HttpConnectionManager_Tracing, e
 		return nil, fmt.Errorf("failed to marshal tracing configuration: %w", err)
 	}
 
-	tags, err := buildTracingTags(tracing.CustomTags)
+	tags, err := buildTracingTags(tracing.CustomTags, tracing.Tags)
 	if err != nil {
 		return nil, fmt.Errorf("failed to build tracing tags: %w", err)
 	}
@@ -161,13 +161,14 @@ func processClusterForTracing(tCtx *types.ResourceVersionTable, tracing *ir.Trac
 	})
 }
 
-func buildTracingTags(tracingTags map[string]egv1a1.CustomTag) ([]*tracingtype.CustomTag, error) {
-	tags := make([]*tracingtype.CustomTag, 0, len(tracingTags))
+func buildTracingTags(tracingTags map[string]egv1a1.CustomTag, tags map[string]string) ([]*tracingtype.CustomTag, error) {
+	out := make([]*tracingtype.CustomTag, 0, len(tracingTags)+len(tags))
+
 	// TODO: consider add some default tags for better UX
 	for k, v := range tracingTags {
 		switch v.Type {
 		case egv1a1.CustomTagTypeLiteral:
-			tags = append(tags, &tracingtype.CustomTag{
+			out = append(out, &tracingtype.CustomTag{
 				Tag: k,
 				Type: &tracingtype.CustomTag_Literal_{
 					Literal: &tracingtype.CustomTag_Literal{
@@ -181,7 +182,7 @@ func buildTracingTags(tracingTags map[string]egv1a1.CustomTag) ([]*tracingtype.C
 				defaultVal = *v.Environment.DefaultValue
 			}
 
-			tags = append(tags, &tracingtype.CustomTag{
+			out = append(out, &tracingtype.CustomTag{
 				Tag: k,
 				Type: &tracingtype.CustomTag_Environment_{
 					Environment: &tracingtype.CustomTag_Environment{
@@ -196,7 +197,7 @@ func buildTracingTags(tracingTags map[string]egv1a1.CustomTag) ([]*tracingtype.C
 				defaultVal = *v.RequestHeader.DefaultValue
 			}
 
-			tags = append(tags, &tracingtype.CustomTag{
+			out = append(out, &tracingtype.CustomTag{
 				Tag: k,
 				Type: &tracingtype.CustomTag_RequestHeader{
 					RequestHeader: &tracingtype.CustomTag_Header{
@@ -209,10 +210,20 @@ func buildTracingTags(tracingTags map[string]egv1a1.CustomTag) ([]*tracingtype.C
 			return nil, fmt.Errorf("unknown custom tag type: %s", v.Type)
 		}
 	}
+
+	for k, v := range tags {
+		out = append(out, &tracingtype.CustomTag{
+			Tag: k,
+			Type: &tracingtype.CustomTag_Value{
+				Value: v,
+			},
+		})
+	}
+
 	// sort tags by tag name, make result consistent
-	sort.Slice(tags, func(i, j int) bool {
-		return tags[i].Tag < tags[j].Tag
+	sort.Slice(out, func(i, j int) bool {
+		return out[i].Tag < out[j].Tag
 	})
 
-	return tags, nil
+	return out, nil
 }

release-notes/current.yaml

@@ -27,6 +27,7 @@ new features: |
   Added support for custom span name.
   Added support for TLS telemetry gRPC backends.
   Added support for addIfAbsent header action in ClientTrafficPolicy EarlyRequestHeaders and LateResponseHeaders to add headers only when they don't already exist.
+  Added support for tracing tag, which allows to use Envoy string command operators such as `%ENVIRONMENT(...)%`.
 
 bug fixes: |
   Fixed configured OIDC authorization endpoint being overridden by discovered endpoints from issuer's well-known URL.

site/content/en/latest/api/extension_types.md

@@ -4252,7 +4252,7 @@ _Appears in:_
 | Field | Type | Required | Default | Description |
 | ---   | ---  | ---      | ---     | ---         |
 | `samplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.4/spec/#fraction)_ |  false  |  | SamplingFraction represents the fraction of requests that should be<br />selected for tracing if no prior sampling decision has been made. |
-| `customTags` | _object (keys:string, values:[CustomTag](#customtag))_ |  false  |  | CustomTags defines the custom tags to add to each span.<br />If provider is kubernetes, pod name and namespace are added by default. |
+| `customTags` | _object (keys:string, values:[CustomTag](#customtag))_ |  false  |  | CustomTags defines the custom tags to add to each span.<br />If provider is kubernetes, pod name and namespace are added by default.<br />Deprecated: Use Tags instead. |
 | `tags` | _object (keys:string, values:string)_ |  false  |  | Tags defines the custom tags to add to each span.<br />Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.<br />The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.<br />If provider is kubernetes, pod name and namespace are added by default.<br />Same keys take precedence over CustomTags. |
 | `spanName` | _[TracingSpanName](#tracingspanname)_ |  false  |  | SpanName defines the name of the span which will be used for tracing.<br />Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.<br />The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.<br />If not set, the span name is provider specific.<br />e.g. Datadog use `ingress` as the default client span name,<br />and `router <UPSTREAM_CLUSTER> egress` as the server span name. |
 | `samplingRate` | _integer_ |  false  |  | SamplingRate controls the rate at which traffic will be<br />selected for tracing if no prior sampling decision has been made.<br />Defaults to 100, valid values [0-100]. 100 indicates 100% sampling.<br />Only one of SamplingRate or SamplingFraction may be specified.<br />If neither field is specified, all requests will be sampled. |
@@ -5329,7 +5329,7 @@ _Appears in:_
 | Field | Type | Required | Default | Description |
 | ---   | ---  | ---      | ---     | ---         |
 | `samplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.4/spec/#fraction)_ |  false  |  | SamplingFraction represents the fraction of requests that should be<br />selected for tracing if no prior sampling decision has been made. |
-| `customTags` | _object (keys:string, values:[CustomTag](#customtag))_ |  false  |  | CustomTags defines the custom tags to add to each span.<br />If provider is kubernetes, pod name and namespace are added by default. |
+| `customTags` | _object (keys:string, values:[CustomTag](#customtag))_ |  false  |  | CustomTags defines the custom tags to add to each span.<br />If provider is kubernetes, pod name and namespace are added by default.<br />Deprecated: Use Tags instead. |
 | `tags` | _object (keys:string, values:string)_ |  false  |  | Tags defines the custom tags to add to each span.<br />Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.<br />The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.<br />If provider is kubernetes, pod name and namespace are added by default.<br />Same keys take precedence over CustomTags. |
 | `spanName` | _[TracingSpanName](#tracingspanname)_ |  false  |  | SpanName defines the name of the span which will be used for tracing.<br />Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.<br />The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.<br />If not set, the span name is provider specific.<br />e.g. Datadog use `ingress` as the default client span name,<br />and `router <UPSTREAM_CLUSTER> egress` as the server span name. |
 

site/content/en/latest/tasks/observability/proxy-trace.md

@@ -347,5 +347,37 @@ spec:
 EOF
 ```
 
+### Custom Tags
+
+You can add custom tags to the traces by setting the `telemetry.tracing.tags` in the [EnvoyProxy][envoy-proxy-crd] CRD.
+You can use the same format as Envoy's [access log command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to define the tag values.
+The following configurations show how to apply proxy with custom tags:
+
+```shell
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyProxy
+metadata:
+  name: otel
+  namespace: envoy-gateway-system
+spec:
+  telemetry:
+    tracing:
+      # sample 100% of requests
+      samplingRate: 100
+      provider:
+        backendRefs:
+        - name: otel-collector
+          namespace: monitoring
+          port: 4317
+        type: OpenTelemetry
+      tags:
+        # This is an example of using a literal as a tag value
+        provider: "otel"
+        "k8s.pod.name": "%ENVIRONMENT(ENVOY_POD_NAME)%"
+        "k8s.namespace.name": "%ENVIRONMENT(ENVOY_POD_NAMESPACE)%"
+        # This is an example of using a header value as a tag value
+        "header1": "%REQUEST_HEADER(X-Header-1)%"
+        "requestedServerName": "%REQUESTED_SERVER_NAME%"
+```
 
 [envoy-proxy-crd]: ../../api/extension_types#envoyproxy

test/e2e/testdata/btp-tracing.yaml

@@ -32,25 +32,11 @@ spec:
           - name: otel-collector
             namespace: monitoring
             port: 4317
-      customTags:
-        "provider":
-          type: Literal
-          literal:
-            value: "otel"
-        "k8s.cluster.name":
-          type: Literal
-          literal:
-            value: "envoy-gateway"
-        "k8s.pod.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAME
-            defaultValue: "-"
-        "k8s.namespace.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAMESPACE
-            defaultValue: "envoy-gateway-system"
+      tags:
+        "provider": "otel"
+        "k8s.cluster.name": "envoy-gateway"
+        "k8s.pod.name": "%ENVIRONMENT(ENVOY_POD_NAME)%"
+        "k8s.namespace.name": "%ENVIRONMENT(ENVOY_POD_NAMESPACE)%"
   shutdown:
     drainTimeout: 5s
     minDrainDuration: 1s
@@ -103,22 +89,8 @@ spec:
     tracing:
       samplingFraction:
         numerator: 100
-      customTags:
-        "provider":
-          type: Literal
-          literal:
-            value: "otel-override"
-        "k8s.cluster.name":
-          type: Literal
-          literal:
-            value: "envoy-gateway"
-        "k8s.pod.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAME
-            defaultValue: "-"
-        "k8s.namespace.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAMESPACE
-            defaultValue: "envoy-gateway-system"
+      tags:
+        "provider": "otel-override"
+        "k8s.cluster.name": "envoy-gateway"
+        "k8s.pod.name": "%ENVIRONMENT(ENVOY_POD_NAME)%"
+        "k8s.namespace.name": "%ENVIRONMENT(ENVOY_POD_NAMESPACE)%"

test/e2e/testdata/tracing-datadog-custom-service-name.yaml

@@ -37,25 +37,11 @@ spec:
             namespace: monitoring
             port: 8126
         serviceName: my-custom-service
-      customTags:
-        "provider":
-          type: Literal
-          literal:
-            value: "datadog"
-        "k8s.cluster.name":
-          type: Literal
-          literal:
-            value: "envoy-gateway"
-        "k8s.pod.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAME
-            defaultValue: "-"
-        "k8s.namespace.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAMESPACE
-            defaultValue: "envoy-gateway-system"
+      tags:
+        "provider": "datadog"
+        "k8s.cluster.name": "envoy-gateway"
+        "k8s.pod.name": "%ENVIRONMENT(ENVOY_POD_NAME)%"
+        "k8s.namespace.name": "%ENVIRONMENT(ENVOY_POD_NAMESPACE)%"
   shutdown:
     drainTimeout: 5s
     minDrainDuration: 1s

test/e2e/testdata/tracing-datadog.yaml

@@ -36,25 +36,11 @@ spec:
           - name: otel-collector
             namespace: monitoring
             port: 8126
-      customTags:
-        "provider":
-          type: Literal
-          literal:
-            value: "datadog"
-        "k8s.cluster.name":
-          type: Literal
-          literal:
-            value: "envoy-gateway"
-        "k8s.pod.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAME
-            defaultValue: "-"
-        "k8s.namespace.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAMESPACE
-            defaultValue: "envoy-gateway-system"
+      tags:
+        "provider": "datadog"
+        "k8s.cluster.name": "envoy-gateway"
+        "k8s.pod.name": "%ENVIRONMENT(ENVOY_POD_NAME)%"
+        "k8s.namespace.name": "%ENVIRONMENT(ENVOY_POD_NAMESPACE)%"
   shutdown:
     drainTimeout: 5s
     minDrainDuration: 1s

test/e2e/testdata/tracing-otel-custom-service-name.yaml

@@ -33,25 +33,11 @@ spec:
             namespace: monitoring
             port: 4317
         serviceName: my-custom-service
-      customTags:
-        "provider":
-          type: Literal
-          literal:
-            value: "otel"
-        "k8s.cluster.name":
-          type: Literal
-          literal:
-            value: "envoy-gateway"
-        "k8s.pod.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAME
-            defaultValue: "-"
-        "k8s.namespace.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAMESPACE
-            defaultValue: "envoy-gateway-system"
+      tags:
+        "provider": "otel"
+        "k8s.cluster.name": "envoy-gateway"
+        "k8s.pod.name": "%ENVIRONMENT(ENVOY_POD_NAME)%"
+        "k8s.namespace.name": "%ENVIRONMENT(ENVOY_POD_NAMESPACE)%"
   shutdown:
     drainTimeout: 5s
     minDrainDuration: 1s

test/e2e/testdata/tracing-zipkin-span-name.yaml

@@ -46,25 +46,11 @@ spec:
             port: 9411
         zipkin:
           enable128BitTraceId: true
-      customTags:
-        "provider":
-          type: Literal
-          literal:
-            value: "zipkin"
-        "k8s.cluster.name":
-          type: Literal
-          literal:
-            value: "envoy-gateway"
-        "k8s.pod.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAME
-            defaultValue: "-"
-        "k8s.namespace.name":
-          type: Environment
-          environment:
-            name: ENVOY_POD_NAMESPACE
-            defaultValue: "envoy-gateway-system"
+      tags:
+        "provider": "zipkin"
+        "k8s.cluster.name": "envoy-gateway"
+        "k8s.pod.name": "%ENVIRONMENT(ENVOY_POD_NAME)%"
+        "k8s.namespace.name": "%ENVIRONMENT(ENVOY_POD_NAMESPACE)%"
 ---
 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute