feat: Set client samplint to 0 by default

z.s.zakharov · zirain · commit c9adef949c42 · 2026-07-08T21:54:45.000+08:00
Signed-off-by: z.s.zakharov &lt;z.s.zakharov@tinkoff.ru&gt;
diff --git a/api/v1alpha1/shared_types.go b/api/v1alpha1/shared_types.go
@@ -943,6 +943,8 @@ type Tracing struct {
 	SamplingFraction *gwapiv1.Fraction `json:"samplingFraction,omitempty"`
 	// ClientSamplingFraction represents the fraction of requests that should be
 	// selected for tracing when requested by the client.
+	// If unspecified, client-forced tracing is disabled by default and users must
+	// set this field to opt in.
 	//
 	// +optional
 	ClientSamplingFraction *gwapiv1.Fraction `json:"clientSamplingFraction,omitempty"`
diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
@@ -3156,6 +3156,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml
@@ -16331,6 +16331,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
@@ -3155,6 +3155,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
@@ -16330,6 +16330,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-datadog-uds.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-datadog-uds.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           customTags:
           - environment:
               defaultValue: '-'
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-datadog.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-datadog.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           customTags:
           - environment:
               defaultValue: '-'
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-endpoint-stats.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-endpoint-stats.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           customTags:
           - environment:
               defaultValue: '-'
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-otel-headers.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-otel-headers.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           overallSampling:
             value: 100
           provider:
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-otel-sampler-always-on.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-otel-sampler-always-on.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           overallSampling:
             value: 100
           provider:
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-otel-sampler.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-otel-sampler.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           overallSampling:
             value: 100
           provider:
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-span-name.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-span-name.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           operation: '%REQ(X-ENVOY-ORIGINAL-HOST)%%PATH(NQ:ORIG)%'
           overallSampling:
             value: 100
@@ -83,8 +82,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-8888
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           operation: '%REQ(X-ENVOY-ORIGINAL-HOST)%%PATH(NQ:ORIG)%'
           overallSampling:
             value: 100
diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-zipkin.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-zipkin.listeners.yaml
@@ -29,8 +29,7 @@
         serverHeaderTransformation: PASS_THROUGH
         statPrefix: http-10080
         tracing:
-          clientSampling:
-            value: 100
+          clientSampling: {}
           customTags:
           - environment:
               defaultValue: '-'
diff --git a/internal/xds/translator/tracing.go b/internal/xds/translator/tracing.go
@@ -116,7 +116,9 @@ func buildHCMTracing(tracing *ir.Tracing) (*hcm.HttpConnectionManager_Tracing, e
 
 	return &hcm.HttpConnectionManager_Tracing{
 		ClientSampling: &xdstype.Percent{
-			Value: ptr.Deref(tracing.ClientSamplingRate, 100),
+			// Default to 0 so Envoy Gateway does not honor client-forced tracing
+			// unless users explicitly opt in with clientSamplingFraction.
+			Value: ptr.Deref(tracing.ClientSamplingRate, 0),
 		},
 		OverallSampling: &xdstype.Percent{
 			Value: ptr.Deref(tracing.OverallSamplingRate, 100),
diff --git a/internal/xds/translator/tracing_test.go b/internal/xds/translator/tracing_test.go
@@ -16,24 +16,58 @@ import (
 )
 
 func TestBuildHCMTracingSampling(t *testing.T) {
-	tracing := &ir.Tracing{
-		ServiceName:         "test-service",
-		SamplingRate:        10,
-		ClientSamplingRate:  new(20.0),
-		OverallSamplingRate: new(30.0),
-		Destination: ir.RouteDestination{
-			Name: "tracing",
+	testCases := []struct {
+		name                    string
+		tracing                 *ir.Tracing
+		expectedRandomSampling  float64
+		expectedClientSampling  float64
+		expectedOverallSampling float64
+	}{
+		{
+			name: "explicit sampling values",
+			tracing: &ir.Tracing{
+				ServiceName:         "test-service",
+				SamplingRate:        10,
+				ClientSamplingRate:  new(20.0),
+				OverallSamplingRate: new(30.0),
+				Destination: ir.RouteDestination{
+					Name: "tracing",
+				},
+				Provider: egv1a1.TracingProvider{
+					Type: egv1a1.TracingProviderTypeOpenTelemetry,
+				},
+			},
+			expectedRandomSampling:  10.0,
+			expectedClientSampling:  20.0,
+			expectedOverallSampling: 30.0,
 		},
-		Provider: egv1a1.TracingProvider{
-			Type: egv1a1.TracingProviderTypeOpenTelemetry,
+		{
+			name: "unset client sampling defaults to zero",
+			tracing: &ir.Tracing{
+				ServiceName:  "test-service",
+				SamplingRate: 10,
+				Destination: ir.RouteDestination{
+					Name: "tracing",
+				},
+				Provider: egv1a1.TracingProvider{
+					Type: egv1a1.TracingProviderTypeOpenTelemetry,
+				},
+			},
+			expectedRandomSampling:  10.0,
+			expectedClientSampling:  0.0,
+			expectedOverallSampling: 100.0,
 		},
 	}
 
-	got, err := buildHCMTracing(tracing)
-	require.NoError(t, err)
-	require.Equal(t, 10.0, got.RandomSampling.Value)
-	require.Equal(t, 20.0, got.ClientSampling.Value)
-	require.Equal(t, 30.0, got.OverallSampling.Value)
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := buildHCMTracing(tc.tracing)
+			require.NoError(t, err)
+			require.Equal(t, tc.expectedRandomSampling, got.RandomSampling.Value)
+			require.Equal(t, tc.expectedClientSampling, got.ClientSampling.Value)
+			require.Equal(t, tc.expectedOverallSampling, got.OverallSampling.Value)
+		})
+	}
 }
 
 func TestBuildSampler(t *testing.T) {
diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
@@ -5016,7 +5016,7 @@ _Appears in:_
 | Field | Type | Required | Default | Description |
 | ---   | ---  | ---      | ---     | ---         |
 | `samplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | SamplingFraction represents the fraction of requests that should be<br />selected for tracing if no prior sampling decision has been made. |
-| `clientSamplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | ClientSamplingFraction represents the fraction of requests that should be<br />selected for tracing when requested by the client. |
+| `clientSamplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | ClientSamplingFraction represents the fraction of requests that should be<br />selected for tracing when requested by the client.<br />If unspecified, client-forced tracing is disabled by default and users must<br />set this field to opt in. |
 | `overallSamplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | OverallSamplingFraction represents the fraction of requests that should be<br />selected for tracing after all other sampling checks have been applied. |
 | `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. |
@@ -6313,7 +6313,7 @@ _Appears in:_
 | Field | Type | Required | Default | Description |
 | ---   | ---  | ---      | ---     | ---         |
 | `samplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | SamplingFraction represents the fraction of requests that should be<br />selected for tracing if no prior sampling decision has been made. |
-| `clientSamplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | ClientSamplingFraction represents the fraction of requests that should be<br />selected for tracing when requested by the client. |
+| `clientSamplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | ClientSamplingFraction represents the fraction of requests that should be<br />selected for tracing when requested by the client.<br />If unspecified, client-forced tracing is disabled by default and users must<br />set this field to opt in. |
 | `overallSamplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#fraction)_ |  false  |  | OverallSamplingFraction represents the fraction of requests that should be<br />selected for tracing after all other sampling checks have been applied. |
 | `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. |
diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml
@@ -27773,6 +27773,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
@@ -50044,6 +50046,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml
@@ -3711,6 +3711,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
@@ -25982,6 +25984,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml
@@ -3711,6 +3711,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
@@ -25982,6 +25984,8 @@ spec:
                         description: |-
                           ClientSamplingFraction represents the fraction of requests that should be
                           selected for tracing when requested by the client.
+                          If unspecified, client-forced tracing is disabled by default and users must
+                          set this field to opt in.
                         properties:
                           denominator:
                             default: 100
