Skip to content

feat: support client and overall tracing sampling #9402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arkodg merged 14 commits into from
Jul 18, 2026
Merged

feat: support client and overall tracing sampling #9402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
26b872f
feat: support client and overall tracing sampling
Ri7ay Jul 1, 2026
3764371
feat: left only fraction
Ri7ay Jul 2, 2026
6cfae1b
feat: Add E2E sampling tests
Jul 6, 2026
cbf1eba
feat: add wait until pattern
Ri7ay Jul 6, 2026
c9adef9
feat: Set client samplint to 0 by default
Jul 8, 2026
4390d77
feat: info in breaking_changes
Jul 8, 2026
5df7926
Merge branch 'main' into client-overall-tracing-sampling
Ri7ay Jul 9, 2026
95843d9
Merge branch 'main' into client-overall-tracing-sampling
Ri7ay Jul 9, 2026
84502c7
Merge branch 'main' into client-overall-tracing-sampling
Ri7ay Jul 10, 2026
8d1e2af
Merge branch 'main' into client-overall-tracing-sampling
Ri7ay Jul 10, 2026
e91bbff
Merge branch 'main' into client-overall-tracing-sampling
Ri7ay Jul 11, 2026
6681db3
feat: set client sampling to zero
Ri7ay Jul 15, 2026
63c42d4
Merge branch 'main' into client-overall-tracing-sampling
Ri7ay Jul 17, 2026
e2124f9
Merge branch 'main' into client-overall-tracing-sampling
Ri7ay Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions api/v1alpha1/shared_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -947,6 +947,18 @@ type Tracing struct {
//
// +optional
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"`

@arkodg arkodg Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • can we change the defaults of disabling clientSamplingFraction to 0, so users need to opt in to this feature ? we'll need to note this in the breaking changes section
  • can we avoid overallSamplingFraction ?

wdyt @envoyproxy/gateway-maintainers

@Ri7ay Ri7ay Jul 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Asked below about the default value 0

@Ri7ay Ri7ay Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

// OverallSamplingFraction represents the fraction of requests that should be
// selected for tracing after all other sampling checks have been applied.
//
// +optional
OverallSamplingFraction *gwapiv1.Fraction `json:"overallSamplingFraction,omitempty"`

@arkodg arkodg Jul 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we avoid OverallSamplingFraction since ClientSamplingFraction now defaults to 0 ?

@Ri7ay Ri7ay Jul 12, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’d keep OverallSamplingFraction. ClientSamplingFraction=0 only disables client-triggered tracing via x-client-trace-id, while OverallSamplingFraction is still useful as the final cap on total trace volume across all sampling paths.

@arkodg arkodg Jul 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok lets keep it, if we think this is a legit use case,

      samplingRate: 1
      clientSamplingRate: 50
      overallSamplingRate: 10

my preference would be to set explicit individual rates, vs a global cap, wdyt @envoyproxy/gateway-maintainers

@Ri7ay Ri7ay Jul 13, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#9402 (comment)

// CustomTags defines the custom tags to add to each span.
// If provider is kubernetes, pod name and namespace are added by default.
//
Expand Down
10 changes: 10 additions & 0 deletions api/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

42 changes: 42 additions & 0 deletions ...s/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3152,6 +3152,28 @@ spec:

This takes precedence over EnvoyProxy tracing when set.
properties:
clientSamplingFraction:
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
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
customTags:
additionalProperties:
properties:
Expand Down Expand Up @@ -3216,6 +3238,26 @@ spec:

Deprecated: Use Tags instead.
type: object
overallSamplingFraction:
description: |-
OverallSamplingFraction represents the fraction of requests that should be
selected for tracing after all other sampling checks have been applied.
properties:
denominator:
default: 100
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
samplingFraction:
description: |-
SamplingFraction represents the fraction of requests that should be
Expand Down
42 changes: 42 additions & 0 deletions charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16329,6 +16329,28 @@ spec:
Tracing defines tracing configuration for managed proxies.
If unspecified, will not send tracing data.
properties:
clientSamplingFraction:
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
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
customTags:
additionalProperties:
properties:
Expand Down Expand Up @@ -16393,6 +16415,26 @@ spec:

Deprecated: Use Tags instead.
type: object
overallSamplingFraction:
description: |-
OverallSamplingFraction represents the fraction of requests that should be
selected for tracing after all other sampling checks have been applied.
properties:
denominator:
default: 100
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
provider:
description: Provider defines the tracing provider.
properties:
Expand Down
42 changes: 42 additions & 0 deletions ...gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3151,6 +3151,28 @@ spec:

This takes precedence over EnvoyProxy tracing when set.
properties:
clientSamplingFraction:
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
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
customTags:
additionalProperties:
properties:
Expand Down Expand Up @@ -3215,6 +3237,26 @@ spec:

Deprecated: Use Tags instead.
type: object
overallSamplingFraction:
description: |-
OverallSamplingFraction represents the fraction of requests that should be
selected for tracing after all other sampling checks have been applied.
properties:
denominator:
default: 100
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
samplingFraction:
description: |-
SamplingFraction represents the fraction of requests that should be
Expand Down
42 changes: 42 additions & 0 deletions charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16328,6 +16328,28 @@ spec:
Tracing defines tracing configuration for managed proxies.
If unspecified, will not send tracing data.
properties:
clientSamplingFraction:
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
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
customTags:
additionalProperties:
properties:
Expand Down Expand Up @@ -16392,6 +16414,26 @@ spec:

Deprecated: Use Tags instead.
type: object
overallSamplingFraction:
description: |-
OverallSamplingFraction represents the fraction of requests that should be
selected for tracing after all other sampling checks have been applied.
properties:
denominator:
default: 100
format: int32
minimum: 1
type: integer
numerator:
format: int32
minimum: 0
type: integer
required:
- numerator
type: object
x-kubernetes-validations:
- message: numerator must be less than or equal to denominator
rule: self.numerator <= self.denominator
provider:
description: Provider defines the tracing provider.
properties:
Expand Down
10 changes: 6 additions & 4 deletions internal/gatewayapi/backendtrafficpolicy.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1191,10 +1191,12 @@ func buildBackendTracing(tracing *egv1a1.Tracing) *ir.BackendTracing {
return nil
}
return &ir.BackendTracing{
SamplingFraction: tracing.SamplingFraction,
CustomTags: ir.CustomTagMapToSlice(tracing.CustomTags),
Tags: ir.MapToSlice(tracing.Tags),
SpanName: tracing.SpanName,
SamplingFraction: tracing.SamplingFraction,
ClientSamplingFraction: tracing.ClientSamplingFraction,
OverallSamplingFraction: tracing.OverallSamplingFraction,
CustomTags: ir.CustomTagMapToSlice(tracing.CustomTags),
Tags: ir.MapToSlice(tracing.Tags),
SpanName: tracing.SpanName,
}
}

Expand Down
49 changes: 30 additions & 19 deletions internal/gatewayapi/listener.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1015,12 +1015,14 @@ func (t *Translator) processTracing(gwCtx *GatewayContext, envoyproxy *egv1a1.En
}

return &ir.Tracing{
Authority: authority,
ServiceName: serviceName,
SamplingRate: proxySamplingRate(tracing),
CustomTags: ir.CustomTagMapToSlice(tracing.CustomTags),
Tags: ir.MapToSlice(tracing.Tags),
ResourceAttributes: ir.MapToSlice(getOpenTelemetryTracingResourceAttributes(&tracing.Provider)),
Authority: authority,
ServiceName: serviceName,
SamplingRate: proxySamplingRate(tracing.SamplingRate, tracing.SamplingFraction),
ClientSamplingRate: proxySamplingFractionPtr(tracing.ClientSamplingFraction),
OverallSamplingRate: proxySamplingFractionPtr(tracing.OverallSamplingFraction),
CustomTags: ir.CustomTagMapToSlice(tracing.CustomTags),
Tags: ir.MapToSlice(tracing.Tags),
ResourceAttributes: ir.MapToSlice(getOpenTelemetryTracingResourceAttributes(&tracing.Provider)),
Destination: ir.RouteDestination{
Name: destName,
Settings: ds,
Expand All @@ -1033,20 +1035,29 @@ func (t *Translator) processTracing(gwCtx *GatewayContext, envoyproxy *egv1a1.En
}, nil
}

func proxySamplingRate(tracing *egv1a1.ProxyTracing) float64 {
rate := 100.0
if tracing.SamplingRate != nil {
rate = float64(*tracing.SamplingRate)
} else if tracing.SamplingFraction != nil {
numerator := float64(tracing.SamplingFraction.Numerator)
denominator := ptr.Deref(tracing.SamplingFraction.Denominator, 100)

rate = numerator * 100 / float64(denominator)
// Identifies a percentage, in the range [0.0, 100.0]
rate = math.Max(0, rate)
rate = math.Min(100, rate)
func proxySamplingFractionPtr(fraction *gwapiv1.Fraction) *float64 {
if fraction == nil {
return nil
}
return new(proxySamplingRate(nil, fraction))
}

func proxySamplingRate(rate *uint32, fraction *gwapiv1.Fraction) float64 {
if rate != nil {
return float64(*rate)
}
return rate
if fraction == nil {
return 100.0
}

numerator := float64(fraction.Numerator)
denominator := ptr.Deref(fraction.Denominator, 100)

value := numerator * 100 / float64(denominator)
// Identifies a percentage, in the range [0.0, 100.0]
value = math.Max(0, value)
value = math.Min(100, value)
return value
}

// getAuthorityFromDestination extracts the gRPC authority from a destination setting.
Expand Down
Loading
Loading