From 6bf817c754c910ea72ea8c096bb44d9b1fb1c3cf Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Mon, 9 Feb 2026 14:58:10 -0800 Subject: [PATCH 01/19] TelemetryPolicy proposal This change include context, problem description, and design objectives for a TelemetryPolicy proposal. If the community agrees on this context then I will follow up with the actual API specification. --- docs/proposals/0069-TelemetryPolicy.md | 49 ++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/proposals/0069-TelemetryPolicy.md diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md new file mode 100644 index 00000000..ca843962 --- /dev/null +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -0,0 +1,49 @@ +Date: 9th February 2026
+Authors: gkhom
+Status: draft
+ +# TelemetryPolicy +A Kubernetes API for Gateway/Mesh Observability + +## Summary +This proposal introduces the `TelemetryPolicy`, a direct policy attachment designed to configure observability signals (metrics, logs, traces) +for Gateway API resources (via `Gateway` attachment) and Service Mesh resources (via `namespace` attachment). + +This K8s API standardizes how users enable and configure telemetry across different data plane implementations, replacing vendor-specific CRDs +with a unified, portable spec. + +# Context +## The Fragmentation of Observability +In the current Kubernetes landscape, the “Who, What, Where, and How Long” of network traffic is answered differently depending on the underlying +proxy technology. While the Gateway API specification has unified how traffic is routed via `HTTPRoute` and `Gateway`, it has deferred the standardization +of how that traffic is observed. +This deferral has led to "Observability Lock-in". Platform Engineering teams are forced to learn and manage distinct APIs for each environment. +A standardized `TelemetryPolicy` is necessary to decouple the intent of observability from the implementation. Without such standardization it is +difficult for platform owners to: + +1. Enforce consistent auditing standards across different infrastructure providers. +2. Support emerging workloads like AI Agents, which require specialized metrics (e.g., token usage, model latency) and detailed audit logs for tool-use verification. +3. Manage “Mesh” and “Gateway” observability with a single unified API. + +## The Emergence of Agentic Networking + +The most pressing driver for this proposal is the shift in traffic patterns introduced by agentic workloads. We are moving from a deterministic Service-to-Service +paradigm to a non-deterministic Agent-to-Tool and Agent-to-Agent paradigm. + +In an Agentic Mesh: +* **Entities are Autonomous**: An AI Agent (Pod) decides entirely on its own to call a Tool (Service). +* **Cost is Volatile**: Usage is measured in tokens, not just requests. A single HTTP 200 OK could cost $0.01 or $10.00 depending on the prompt and model used. +* **Context is King**: Debugging requires knowing the semantic context: Which Model? Which Prompt? Which tool? + +Existing telemetry policies are unaware of the Generative AI semantic conventions. They see an opaque TCP stream or HTTP POST. Without a standardized API to +configure the extraction and export of these attributes, the “Agentic Mesh” will remain a black box, increasing governance and cost control challenges. + +## Design Objectives + +To address these challenges, the `TelemetryPolicy` proposal targets four core objectives: + +1. **Standardization**: A single API for Gateway and Mesh to configure Access Logging, Metrics generation, and Tracing propagation. +2. **GEP-713 Compliance**: Support `targetRef` attachment to `Gateway` and `Namespace`. The latter covers Mesh use-cases. +3. **Agentic Support**: Enable the capture of OpenTelemetry GenAI Semantic Conventions and support the requirements of PR #33. +4. **Protocol Agnostic**: Support OpenTelemetry as the primary data model while allowing vendor-specific extensions. + From 40e812f1a24cf3d681e6718858dc673f60915604 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 11 Feb 2026 14:15:10 -0800 Subject: [PATCH 02/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index ca843962..9def6a5b 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -35,7 +35,7 @@ In an Agentic Mesh: * **Cost is Volatile**: Usage is measured in tokens, not just requests. A single HTTP 200 OK could cost $0.01 or $10.00 depending on the prompt and model used. * **Context is King**: Debugging requires knowing the semantic context: Which Model? Which Prompt? Which tool? -Existing telemetry policies are unaware of the Generative AI semantic conventions. They see an opaque TCP stream or HTTP POST. Without a standardized API to +Existing telemetry policies are unaware of the emerging Generative AI semantic conventions. They see an opaque TCP stream or HTTP POST. Without a standardized API to configure the extraction and export of these attributes, the “Agentic Mesh” will remain a black box, increasing governance and cost control challenges. ## Design Objectives From 26b328a204bf913f1bf730060efe72ae13bb9f0d Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Tue, 17 Feb 2026 15:53:15 -0800 Subject: [PATCH 03/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 145 +++++++++++++++++++++++++ 1 file changed, 145 insertions(+) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 9def6a5b..8eb5ee76 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -47,3 +47,148 @@ To address these challenges, the `TelemetryPolicy` proposal targets four core ob 3. **Agentic Support**: Enable the capture of OpenTelemetry GenAI Semantic Conventions and support the requirements of PR #33. 4. **Protocol Agnostic**: Support OpenTelemetry as the primary data model while allowing vendor-specific extensions. +## The TelemetryPolicy Specification + +We propose the `TelemetryPolicy` as a direct policy attachment in the `gateway.networking.k8s.io` API group. + +### Resource Structure + +The following is an example that demonstrates the structure of the `TelemetryPolicy`. + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: TelemetryPolicy +metadata: + name: standard-telemetry + namespace: prod-ns +spec: + # GEP-713 Attachment + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: my-gateway + + # 1. Tracing Configuration + tracing: + provider: + type: OTLP # or implementation-specific + endpoint: "otel-collector.monitoring.svc:4317" + samplingRate: + percent: 5 + parentBasedSampling: + enabled: true + samplingRate: + percent: 50 + context: + - W3C + - B3 + customSpanAttributes: + - attributeName: "env" + literalValue: "production" + + # 2. Metrics Configuration + metrics: + enable: true + provider: + type: Prometheus + overrides: + - name: "request_count" + type: Counter + dimensions: # Custom labels/dimensions + - key: "model_id" + fromHeader: "x-model-id" # Crucial for Agentic workloads + + # 3. Access Logging + accessLogs: + enable: true + format: JSON + matches: # Conditional logging + - path: "/api/v1/sensitive" + fields: # Configure specific fields to include + - "start_time" + - "response_code" + - "x-token-usage" +``` + +### Policy Attachment + +Following [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/), the `TelemetryPolicy` supports the following attachments: + +1. **Gateway (Instance Scope)**: Configures the telemetry for a specific `Gateway`. +2. **Namespace (Mesh Scope)**: Configures the telemetry for all mesh proxies (sidecar proxy / node proxy / etc.) in that namespace. + +#### Alternatives Considered + +##### GatewayClass + +Targeting `GatewayClass` would set the default telemetry configurations for all Gateways of a specific class. While this would provide a powerful mechanism, the challenge is that `GatewayClass` is a cluster-scoped entity whereas `TelemetryPolicy` is namespace-scoped. Allowing a namespace-scoped resource to influence the behavior of an entire cluster introduces significant operational and security risks. We would also need to define the semantics in the presence of multiple `TelemetryPolicy` resources that target the same `GatewayClass`. This is out of scope for this proposal. + +##### Route + +Future iterations could support attachment directly to routes (e.g., `HTTPRoute`). This will allow specific telemetry configuration for critical paths or specific API endpoints. To maintain API simplicity in the initial proposal, this is deferred to a future proposal. + +##### Workload + +We evaluated the ability to target specific workloads directly using pod label selectors. This would allow for precise application of telemetry settings to specific groups of pods (e.g., forcing debug logging on a specific deployment). However, we are prioritizing namespace-level attachment for mesh use-cases to align with existing Gateway API patterns. + +##### Service + +Attachment to a `Service` is deferred because a `Service` resource primarily defines the "exposure" or inbound side of a workload. It is not intuitive for a policy attached to an inbound definition to configure telemetry for both inbound and outbound traffic. Additionally, since multiple Services can select the same Pod, resolving precedence or merging strategies when different `TelemetryPolicy` resources target those different Services introduces significant complexity. + +### Detailed Resource Description + +| Field Name | Type | Description | +| --------------------------------- | ------------ | ----------- | +| spec.targetRef | Object | *Required.* Identifies the target resource (Gateway or Namespace) to which this policy attaches, following GEP-713 compliance. | +| spec.tracing | Object | Configuration for distributed tracing options. | +| spec.tracing.provider | Object | Specifies the tracing backend. Includes type (e.g., "OTLP") and endpoint (e.g., collector URL). | +| spec.tracing.samplingRate | Fraction | The base sampling probability for traces. | +| spec.tracing.parentBasedSampling | Object | Configures whether to respect the sampling decision of the parent span, with an optional fallback sampling rate. | +| spec.tracing.context | List | Specifies the context propagation formats to use (e.g., W3C, B3, Jaeger). | +| spec.tracing.customAttributes | List | Allows appending custom tags/attributes to spans. Supports literal values (e.g., env: production). | +| spec.metrics | Object | Configuration for metric generation and exports. | +| spec.metrics.enable | Boolean | Global switch to enable or disable metric generation. | +| spec.metrics.provider | Object | Specifies the metrics backend (e.g., Prometheus). | +| spec.metrics.overrides | List | List of configurations to customize specific metric families (e.g., request_count). | +| spec.metrics.overrides.dimensions | List | Defines custom dimensions (labels). Can extract values from headers (e.g., x-model-id) for Agentic telemetry. | +| spec.accessLogs | Object | Configuration for access log generation. | +| spec.accessLogs.enable | Boolean | Global switch to enable or disable access logging. | +| spec.accessLogs.format | String | The format of the logs (e.g., JSON, Text). | +| spec.accessLogs.matches | List | Conditions for logging, allowing filtering to specific paths (e.g., /api/v1/sensitive) or events. | +| spec.accessLogs.fields | List | A list of specific fields or headers to include in the logs (e.g., x-token-usage, start_time). | + +### Alignment with Requirements + +#### Agentic Telemetry + +* **Token Counting**: The `metrics.overrides` and `accessLogs.fields` sections allow extracting the values from headers (e.g., `x-usage-input-tokens`, `x-usage-output-tokens`) or request/response bodies (if supported by the data plane) into telemetry. +* **Tool Use Auditing**: By attaching a `TelemetryPolicy` to a `Gateway` serving LLM traffic, operators can enforce 100% access logging for specific routes (e.g., `/tool/execute`) to create an immutable audit trafil of agent actions. +* **Latency Tracking**: Latency histograms can be configured to track "Time to First Token" (TTFT) if exposed by the backend protocol. + +#### Tracing + +* **Sampling**: Supports probabilistic and parent-based sampling. +* **Propagation**: Explicitly configures propagation formats (W3C TraceContext defaults, option B3, Jaeger, etc.) +* **Customization**: Allows appending custom tags/attributes to spans. + +#### Metrics + +* **Granularity**: Users can enable/disable specific metric families. +* **Dimensions**: The API supports "overrides" (similar to [OpenTelemetry Views](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#view)) where users can add or remove dimensions (labels/attributes) to reduce cardinality or increase visibility. + +#### Logging + +* **Flexible Formatting**: Supports both JSON and text formats for compatibility with standard log aggregation stacks. +* **Smart Filtering**: Reduces noise and cost via CEL-based filtering, allowing logs to be generated only for specific events (e.g., 5xx errors, high latency, or critical paths). +* **Custom Attributes**: Enables the extraction of specific headers and proxy metadata into log entries. +* **Sinks**: Defaults to standard container logging (stdout) with extensibility for OTLP or external ports. + +## Comparison with Prior Art + +| | **Istio** | **Envoy Gateway** | **Kong** | **Kuadrant** | **GKE / Inference Gateway** | **TelemetryPolicy**
(this proposal) | +| --- | --- | --- | --- | --- | --- | --- | +| Primary API | [Telemetry CRD](https://istio.io/latest/docs/reference/config/telemetry/) | | | | | | +| Policy Model | | | | | | | +| Metrics & Logs | | | | | | | +| Portability | | | | | | | +| AI/LLM Support | | | | | | | From af83a0debc620c88576b457cb922fd4152466d4c Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Sun, 22 Feb 2026 13:44:09 -0800 Subject: [PATCH 04/19] Update docs/proposals/0069-TelemetryPolicy.md Co-authored-by: Lior Lieberman --- docs/proposals/0069-TelemetryPolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 8eb5ee76..0fabdd06 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -49,7 +49,7 @@ To address these challenges, the `TelemetryPolicy` proposal targets four core ob ## The TelemetryPolicy Specification -We propose the `TelemetryPolicy` as a direct policy attachment in the `gateway.networking.k8s.io` API group. +We propose the `TelemetryPolicy` as a direct policy attachment in the `gateway.networking.k8s.io` API group. See [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/#classes-of-policies) for more information on Direct attachment. ### Resource Structure From c5aed7d931eb5aa82edddb0e9cf37e5a2a29ff8f Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Sun, 22 Feb 2026 13:45:21 -0800 Subject: [PATCH 05/19] Update docs/proposals/0069-TelemetryPolicy.md Co-authored-by: Lior Lieberman --- docs/proposals/0069-TelemetryPolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 0fabdd06..26df002b 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -88,7 +88,7 @@ spec: # 2. Metrics Configuration metrics: - enable: true + enabled: true provider: type: Prometheus overrides: From 167372c229fc873061da42f824230dadc6528821 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Sun, 22 Feb 2026 13:46:08 -0800 Subject: [PATCH 06/19] Update docs/proposals/0069-TelemetryPolicy.md Co-authored-by: Gloire Rubambiza --- docs/proposals/0069-TelemetryPolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 26df002b..060fd95c 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -162,7 +162,7 @@ Attachment to a `Service` is deferred because a `Service` resource primarily def #### Agentic Telemetry * **Token Counting**: The `metrics.overrides` and `accessLogs.fields` sections allow extracting the values from headers (e.g., `x-usage-input-tokens`, `x-usage-output-tokens`) or request/response bodies (if supported by the data plane) into telemetry. -* **Tool Use Auditing**: By attaching a `TelemetryPolicy` to a `Gateway` serving LLM traffic, operators can enforce 100% access logging for specific routes (e.g., `/tool/execute`) to create an immutable audit trafil of agent actions. +* **Tool Use Auditing**: By attaching a `TelemetryPolicy` to a `Gateway` serving LLM traffic, operators can enforce 100% access logging for specific routes (e.g., `/tool/execute`) to create an immutable audit trail of agent actions. * **Latency Tracking**: Latency histograms can be configured to track "Time to First Token" (TTFT) if exposed by the backend protocol. #### Tracing From d402594f041caa288f5bcc98f69f2a143203dbb8 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:56:24 -0800 Subject: [PATCH 07/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 140 +++++++++++++++++++++---- 1 file changed, 120 insertions(+), 20 deletions(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 060fd95c..d11ba8b1 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -82,7 +82,7 @@ spec: context: - W3C - B3 - customSpanAttributes: + customAttributes: - attributeName: "env" literalValue: "production" @@ -137,25 +137,125 @@ Attachment to a `Service` is deferred because a `Service` resource primarily def ### Detailed Resource Description -| Field Name | Type | Description | -| --------------------------------- | ------------ | ----------- | -| spec.targetRef | Object | *Required.* Identifies the target resource (Gateway or Namespace) to which this policy attaches, following GEP-713 compliance. | -| spec.tracing | Object | Configuration for distributed tracing options. | -| spec.tracing.provider | Object | Specifies the tracing backend. Includes type (e.g., "OTLP") and endpoint (e.g., collector URL). | -| spec.tracing.samplingRate | Fraction | The base sampling probability for traces. | -| spec.tracing.parentBasedSampling | Object | Configures whether to respect the sampling decision of the parent span, with an optional fallback sampling rate. | -| spec.tracing.context | List | Specifies the context propagation formats to use (e.g., W3C, B3, Jaeger). | -| spec.tracing.customAttributes | List | Allows appending custom tags/attributes to spans. Supports literal values (e.g., env: production). | -| spec.metrics | Object | Configuration for metric generation and exports. | -| spec.metrics.enable | Boolean | Global switch to enable or disable metric generation. | -| spec.metrics.provider | Object | Specifies the metrics backend (e.g., Prometheus). | -| spec.metrics.overrides | List | List of configurations to customize specific metric families (e.g., request_count). | -| spec.metrics.overrides.dimensions | List | Defines custom dimensions (labels). Can extract values from headers (e.g., x-model-id) for Agentic telemetry. | -| spec.accessLogs | Object | Configuration for access log generation. | -| spec.accessLogs.enable | Boolean | Global switch to enable or disable access logging. | -| spec.accessLogs.format | String | The format of the logs (e.g., JSON, Text). | -| spec.accessLogs.matches | List | Conditions for logging, allowing filtering to specific paths (e.g., /api/v1/sensitive) or events. | -| spec.accessLogs.fields | List | A list of specific fields or headers to include in the logs (e.g., x-token-usage, start_time). | +The following are the Go structs modeling the proposed specification: + +```Go +// TelemetryPolicy defines a direct policy attachment to configure observability +// signals for Gateway API resources and Service Mesh resources. +type TelemetryPolicy struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec TelemetryPolicySpec `json:"spec"` +} + +type TelemetryPolicySpec struct { + // Identifies the target resource (Gateway or Namespace) to which this policy attaches. + TargetRef TargetRef `json:"targetRef"` + + // Configuration for distributed tracing options. + Tracing *TracingConfig `json:"tracing,omitempty"` + + // Configuration for metric generation and exports. + Metrics *MetricsConfig `json:"metrics,omitempty"` + + // Configuration for access log generation. + AccessLogs *AccessLogsConfig `json:"accessLogs,omitempty"` +} + +type TargetRef struct { + Group string `json:"group"` + Kind string `json:"kind"` + Name string `json:"name"` +} + +// --- Tracing Types --- + +type TracingConfig struct { + // Specifies the tracing backend. Includes type (e.g., "OTLP") and endpoint. + Provider *TracingProvider `json:"provider,omitempty"` + + // The base sampling probability for traces. + SamplingRate *Fraction `json:"samplingRate,omitempty"` + + // Configures whether to respect the sampling decision of the parent span. + ParentBasedSampling *ParentBasedSampling `json:"parentBasedSampling,omitempty"` + + // Specifies the context propagation formats to use (e.g., W3C, B3, Jaeger). + Context []string `json:"context,omitempty"` + + // Allows appending custom tags/attributes to spans. + CustomAttributes []CustomAttribute `json:"customAttributes,omitempty"` +} + +type TracingProvider struct { + Type string `json:"type"` + Endpoint string `json:"endpoint,omitempty"` +} + +type Fraction struct { + Percent int32 `json:"percent,omitempty"` +} + +type ParentBasedSampling struct { + Enabled bool `json:"enabled"` + SamplingRate *Fraction `json:"samplingRate,omitempty"` +} + +type CustomAttribute struct { + AttributeName string `json:"attributeName"` + LiteralValue string `json:"literalValue"` +} + +// --- Metrics Types --- + +type MetricsConfig struct { + // Global switch to enable or disable metric generation. + Enabled bool `json:"enabled"` + + // Specifies the metrics backend (e.g., Prometheus). + Provider *MetricsProvider `json:"provider,omitempty"` + + // List of configurations to customize specific metric families. + Overrides []MetricOverride `json:"overrides,omitempty"` +} + +type MetricsProvider struct { + Type string `json:"type"` +} + +type MetricOverride struct { + Name string `json:"name"` + Type string `json:"type,omitempty"` + // Defines custom dimensions (labels). Can extract values from headers. + Dimensions []Dimension `json:"dimensions,omitempty"` +} + +type Dimension struct { + Key string `json:"key"` + FromHeader string `json:"fromHeader,omitempty"` +} + +// --- Access Logs Types --- + +type AccessLogsConfig struct { + // Global switch to enable or disable access logging. + Enabled bool `json:"enabled"` + + // The format of the logs (e.g., JSON, Text). + Format string `json:"format,omitempty"` + + // Conditions for logging, allowing filtering to specific paths or events. + Matches []MatchCondition `json:"matches,omitempty"` + + // A list of specific fields or headers to include in the logs. + Fields []string `json:"fields,omitempty"` +} + +type MatchCondition struct { + Path string `json:"path,omitempty"` +} +``` ### Alignment with Requirements From 71f4338807a37f01fa8b49363f6dab2739af57f7 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Mon, 23 Feb 2026 16:51:20 -0800 Subject: [PATCH 08/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index d11ba8b1..b1cfbb98 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -92,7 +92,7 @@ spec: provider: type: Prometheus overrides: - - name: "request_count" + - name: "gateway.networking.k8s.io/http/request_count" type: Counter dimensions: # Custom labels/dimensions - key: "model_id" @@ -225,6 +225,7 @@ type MetricsProvider struct { } type MetricOverride struct { + // The metric name to override (e.g., "http_requests_total" or "gateway.networking.k8s.io/http/request_count"). Name string `json:"name"` Type string `json:"type,omitempty"` // Defines custom dimensions (labels). Can extract values from headers. From 4943c76510c56b71ed31ae83d740bfbec2029e89 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Tue, 24 Feb 2026 13:43:20 -0800 Subject: [PATCH 09/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 108 ++++++++++++------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index b1cfbb98..b17f6e26 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -143,118 +143,118 @@ The following are the Go structs modeling the proposed specification: // TelemetryPolicy defines a direct policy attachment to configure observability // signals for Gateway API resources and Service Mesh resources. type TelemetryPolicy struct { - metav1.TypeMeta `json:",inline"` - metav1.ObjectMeta `json:"metadata,omitempty"` + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` - Spec TelemetryPolicySpec `json:"spec"` + Spec TelemetryPolicySpec `json:"spec"` } type TelemetryPolicySpec struct { - // Identifies the target resource (Gateway or Namespace) to which this policy attaches. - TargetRef TargetRef `json:"targetRef"` + // Identifies the target resource (Gateway or Namespace) to which this policy attaches. + TargetRef TargetRef `json:"targetRef"` - // Configuration for distributed tracing options. - Tracing *TracingConfig `json:"tracing,omitempty"` + // Configuration for distributed tracing options. + Tracing *TracingConfig `json:"tracing,omitempty"` - // Configuration for metric generation and exports. - Metrics *MetricsConfig `json:"metrics,omitempty"` + // Configuration for metric generation and exports. + Metrics *MetricsConfig `json:"metrics,omitempty"` - // Configuration for access log generation. - AccessLogs *AccessLogsConfig `json:"accessLogs,omitempty"` + // Configuration for access log generation. + AccessLogs *AccessLogsConfig `json:"accessLogs,omitempty"` } type TargetRef struct { - Group string `json:"group"` - Kind string `json:"kind"` - Name string `json:"name"` + Group string `json:"group"` + Kind string `json:"kind"` + Name string `json:"name"` } // --- Tracing Types --- type TracingConfig struct { - // Specifies the tracing backend. Includes type (e.g., "OTLP") and endpoint. - Provider *TracingProvider `json:"provider,omitempty"` + // Specifies the tracing backend. Includes type (e.g., "OTLP") and endpoint. + Provider *TracingProvider `json:"provider,omitempty"` - // The base sampling probability for traces. - SamplingRate *Fraction `json:"samplingRate,omitempty"` + // The base sampling probability for traces. + SamplingRate *Fraction `json:"samplingRate,omitempty"` - // Configures whether to respect the sampling decision of the parent span. - ParentBasedSampling *ParentBasedSampling `json:"parentBasedSampling,omitempty"` + // Configures whether to respect the sampling decision of the parent span. + ParentBasedSampling *ParentBasedSampling `json:"parentBasedSampling,omitempty"` - // Specifies the context propagation formats to use (e.g., W3C, B3, Jaeger). - Context []string `json:"context,omitempty"` + // Specifies the context propagation formats to use (e.g., W3C, B3, Jaeger). + Context []string `json:"context,omitempty"` - // Allows appending custom tags/attributes to spans. - CustomAttributes []CustomAttribute `json:"customAttributes,omitempty"` + // Allows appending custom tags/attributes to spans. + CustomAttributes []CustomAttribute `json:"customAttributes,omitempty"` } type TracingProvider struct { - Type string `json:"type"` - Endpoint string `json:"endpoint,omitempty"` + Type string `json:"type"` + Endpoint string `json:"endpoint,omitempty"` } type Fraction struct { - Percent int32 `json:"percent,omitempty"` + Percent int32 `json:"percent,omitempty"` } type ParentBasedSampling struct { - Enabled bool `json:"enabled"` - SamplingRate *Fraction `json:"samplingRate,omitempty"` + Enabled bool `json:"enabled"` + SamplingRate *Fraction `json:"samplingRate,omitempty"` } type CustomAttribute struct { - AttributeName string `json:"attributeName"` - LiteralValue string `json:"literalValue"` + AttributeName string `json:"attributeName"` + LiteralValue string `json:"literalValue"` } // --- Metrics Types --- type MetricsConfig struct { - // Global switch to enable or disable metric generation. - Enabled bool `json:"enabled"` + // Global switch to enable or disable metric generation. + Enabled bool `json:"enabled"` - // Specifies the metrics backend (e.g., Prometheus). - Provider *MetricsProvider `json:"provider,omitempty"` + // Specifies the metrics backend (e.g., Prometheus). + Provider *MetricsProvider `json:"provider,omitempty"` - // List of configurations to customize specific metric families. - Overrides []MetricOverride `json:"overrides,omitempty"` + // List of configurations to customize specific metric families. + Overrides []MetricOverride `json:"overrides,omitempty"` } type MetricsProvider struct { - Type string `json:"type"` + Type string `json:"type"` } type MetricOverride struct { - // The metric name to override (e.g., "http_requests_total" or "gateway.networking.k8s.io/http/request_count"). - Name string `json:"name"` - Type string `json:"type,omitempty"` - // Defines custom dimensions (labels). Can extract values from headers. - Dimensions []Dimension `json:"dimensions,omitempty"` + // The metric name to override (e.g., "http_requests_total" or "gateway.networking.k8s.io/http/request_count"). + Name string `json:"name"` + Type string `json:"type,omitempty"` + // Defines custom dimensions (labels). Can extract values from headers. + Dimensions []Dimension `json:"dimensions,omitempty"` } type Dimension struct { - Key string `json:"key"` - FromHeader string `json:"fromHeader,omitempty"` + Key string `json:"key"` + FromHeader string `json:"fromHeader,omitempty"` } // --- Access Logs Types --- type AccessLogsConfig struct { - // Global switch to enable or disable access logging. - Enabled bool `json:"enabled"` + // Global switch to enable or disable access logging. + Enabled bool `json:"enabled"` - // The format of the logs (e.g., JSON, Text). - Format string `json:"format,omitempty"` + // The format of the logs (e.g., JSON, Text). + Format string `json:"format,omitempty"` - // Conditions for logging, allowing filtering to specific paths or events. - Matches []MatchCondition `json:"matches,omitempty"` + // Conditions for logging, allowing filtering to specific paths or events. + Matches []MatchCondition `json:"matches,omitempty"` - // A list of specific fields or headers to include in the logs. - Fields []string `json:"fields,omitempty"` + // A list of specific fields or headers to include in the logs. + Fields []string `json:"fields,omitempty"` } type MatchCondition struct { - Path string `json:"path,omitempty"` + Path string `json:"path,omitempty"` } ``` From eb826bcafe70122c09d1d806fc4657efeabfde64 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 4 Mar 2026 21:40:44 -0800 Subject: [PATCH 10/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 37 +++++++++++++++++++++----- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index b17f6e26..79da926e 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -286,10 +286,33 @@ type MatchCondition struct { ## Comparison with Prior Art -| | **Istio** | **Envoy Gateway** | **Kong** | **Kuadrant** | **GKE / Inference Gateway** | **TelemetryPolicy**
(this proposal) | -| --- | --- | --- | --- | --- | --- | --- | -| Primary API | [Telemetry CRD](https://istio.io/latest/docs/reference/config/telemetry/) | | | | | | -| Policy Model | | | | | | | -| Metrics & Logs | | | | | | | -| Portability | | | | | | | -| AI/LLM Support | | | | | | | +### Istio + +[Istio](https://istio.io/)'s `Telemetry` API is the most direct prior art that inspired this proposal. It allows configuring observability at the mesh, namespace, and workload level. + +* **Metrics**: Istio allows users to enable/disable specific metrics, add custom dimensions, and configure providers. +* **Logs**: Istio supports access logging configurations with CEL-like expressions for advanced filtering. +* **Traces**: Istio supports probabilistic sampling, context propagation, and custom span tags. +* **Customization**: For advanced telemetry use-cases not natively covered by the `Telemetry` API, Istio users can fall back to using `EnvoyFilter` resources. While highly flexible, `EnvoyFilter` requires deep knowledge of Envoy's internal xDS API. This is tightly coupled to the data plane implementation and can be brittle across version upgrades. +* **Comparison**: The proposed `TelemetryPolicy` adapts Istio's powerful intent-based capabilities to the standardized Gateway API attachment model. + +### Envoy Gateway + +[Envoy Gateway](https://gateway.envoyproxy.io/) configures observability through two distinct custom resources: `EnvoyGateway` for the control plane and `EnvoyProxy` for the underlying data plane proxies. + +* **Metrics**: Envoy Gateway allows configuring Prometheus and OpenTelemetry sinks for both the control plane (using `EnvoyGateway` CRD) and the data plane proxies (using the `EnvoyProxy` CRD). +* **Logs**: Proxy access logs are configured via the `EnvoyProxy` resource. It supports exporting to file, OTLP, or gRPC Access Log Service (ALS) sinks. It uses CEL expressions for smart filtering (e.g., matching specific headers), and allows applying log configurations at the Route or Listener level. +* **Tracing**: Tracing is configured in the `EnvoyProxy` resource. It supports OpenTelemetry, Zipkin, and Datadog providers. It allows configuring sampling and supports appending custom tags derived from literals, environment variables, or request headers. +* **Customization**: For advanced telemetry use-cases not covered natively, users can fall back to the `EnvoyPatchPolicy` API to mutate the underlying xDS configuration using JSON Patch semantics. This is similar to Istio's `EnvoyFilter`. +* **Comparison**: While Envoy Gateway provides a robust, native telemetry configuration, it is tightly coupled to infrastructure-oriented CRDs. The proposed `TelemetryPolicy` allows users to configure telemetry behaviors using a portable `targetRef` model, without binding their observability intent to an Envoy-specific schema. + +### Kuadrant + +[Kuadrant](https://kuadrant.io/) provides observability for API management features like rate limiting and authentication. It is configured through a mix of its own custom resources and the underlying gateway's APIs. + +* **Metrics**: Kuadrant enables metrics via the `Kuadrant` CR. It also introduces its own `TelemetryPolicy` API (extensions.kuadrant.io/v1alpha1) to add custom dimensions to metrics. +* **Logs**: For proxy access logging, Kuadrant relies on the underlying gateway provider (e.g., Istio's Telemetry API). However, it configures request correlation across its own components (Authorino, Limitador, and Wasm-shim) by specifying HTTP header identifiers in the `Kuadrant` CR. +* **Tracing**: Tracing is configured centrally via the `Kuadrant` CR. It exports OpenTelemetry spans for both the control plane and data plane components. It supports global trace filtering levels to control the verbosity of exported spans. +* **Customization**: To make low-level, custom modifications to the data plane configuration that are not supported by Kuadrant's native APIs, users can bypass Kuadrant and directly use the underlying gateway's mechanisms. +* **Comparison**: While Kuadrant provides powerful, identity-aware telemetry (like token tracking per user), its configuration is fragmented across the `Kuadrant` CR, components specific CRDs, its custom extension `TelemetryPolicy`, and the underlying gateway's native APIs. The proposed `TelemetryPolicy` unified these intent-based capabilities into a single, provider-agnostic resource. + From 38d78dcd92006434adbf72eda9dc525fb4f1da78 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 4 Mar 2026 21:42:43 -0800 Subject: [PATCH 11/19] Update docs/proposals/0069-TelemetryPolicy.md Co-authored-by: Evaline Ju <69598118+evaline-ju@users.noreply.github.com> --- docs/proposals/0069-TelemetryPolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 79da926e..b11fc861 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -100,7 +100,7 @@ spec: # 3. Access Logging accessLogs: - enable: true + enabled: true format: JSON matches: # Conditional logging - path: "/api/v1/sensitive" From 04667c733c5bf449a9cd1c1d982bc7dcd1cae413 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 4 Mar 2026 21:58:09 -0800 Subject: [PATCH 12/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index b11fc861..1bf98c31 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -104,6 +104,7 @@ spec: format: JSON matches: # Conditional logging - path: "/api/v1/sensitive" + - cel: "response.code >= 500" # CEL-based filtering for errors fields: # Configure specific fields to include - "start_time" - "response_code" @@ -254,7 +255,11 @@ type AccessLogsConfig struct { } type MatchCondition struct { + // Path allows filtering to specific paths. Path string `json:"path,omitempty"` + + // CEL provides an expression for advanced filtering (e.g., matching response codes, headers). + CEL string `json:"cel,omitempty"` } ``` From 7589829906ea7e9537bbeb83837d43513b2a5a9e Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 4 Mar 2026 22:24:04 -0800 Subject: [PATCH 13/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 1bf98c31..105a3adb 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -63,8 +63,8 @@ metadata: namespace: prod-ns spec: # GEP-713 Attachment - targetRef: - group: gateway.networking.k8s.io + targetRefs: + - group: gateway.networking.k8s.io kind: Gateway name: my-gateway @@ -151,8 +151,8 @@ type TelemetryPolicy struct { } type TelemetryPolicySpec struct { - // Identifies the target resource (Gateway or Namespace) to which this policy attaches. - TargetRef TargetRef `json:"targetRef"` + // Identifies the target resources (Gateway or Namespace) to which this policy attaches (GEP-713). + TargetRefs []TargetReference `json:"targetRefs"` // Configuration for distributed tracing options. Tracing *TracingConfig `json:"tracing,omitempty"` @@ -164,12 +164,6 @@ type TelemetryPolicySpec struct { AccessLogs *AccessLogsConfig `json:"accessLogs,omitempty"` } -type TargetRef struct { - Group string `json:"group"` - Kind string `json:"kind"` - Name string `json:"name"` -} - // --- Tracing Types --- type TracingConfig struct { From 297b6b3fd49564f39dc83b084774cddc95c57ffe Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 11 Mar 2026 22:15:39 -0700 Subject: [PATCH 14/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 105a3adb..66bc5085 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -49,14 +49,14 @@ To address these challenges, the `TelemetryPolicy` proposal targets four core ob ## The TelemetryPolicy Specification -We propose the `TelemetryPolicy` as a direct policy attachment in the `gateway.networking.k8s.io` API group. See [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/#classes-of-policies) for more information on Direct attachment. +We propose the `TelemetryPolicy` as a direct policy attachment in the `agentic.networking.k8s.io` API group. See [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/#classes-of-policies) for more information on Direct attachment. ### Resource Structure The following is an example that demonstrates the structure of the `TelemetryPolicy`. ```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 +apiVersion: agentic.networking.x-k8s.io/v1alpha1 kind: TelemetryPolicy metadata: name: standard-telemetry From 1a3981057d934b64c5895eccce03a1de89f8275e Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 1 Apr 2026 18:22:42 -0700 Subject: [PATCH 15/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 66bc5085..c6aabf43 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -71,7 +71,6 @@ spec: # 1. Tracing Configuration tracing: provider: - type: OTLP # or implementation-specific endpoint: "otel-collector.monitoring.svc:4317" samplingRate: percent: 5 @@ -79,9 +78,6 @@ spec: enabled: true samplingRate: percent: 50 - context: - - W3C - - B3 customAttributes: - attributeName: "env" literalValue: "production" @@ -176,15 +172,11 @@ type TracingConfig struct { // Configures whether to respect the sampling decision of the parent span. ParentBasedSampling *ParentBasedSampling `json:"parentBasedSampling,omitempty"` - // Specifies the context propagation formats to use (e.g., W3C, B3, Jaeger). - Context []string `json:"context,omitempty"` - // Allows appending custom tags/attributes to spans. CustomAttributes []CustomAttribute `json:"customAttributes,omitempty"` } type TracingProvider struct { - Type string `json:"type"` Endpoint string `json:"endpoint,omitempty"` } @@ -208,17 +200,10 @@ type MetricsConfig struct { // Global switch to enable or disable metric generation. Enabled bool `json:"enabled"` - // Specifies the metrics backend (e.g., Prometheus). - Provider *MetricsProvider `json:"provider,omitempty"` - // List of configurations to customize specific metric families. Overrides []MetricOverride `json:"overrides,omitempty"` } -type MetricsProvider struct { - Type string `json:"type"` -} - type MetricOverride struct { // The metric name to override (e.g., "http_requests_total" or "gateway.networking.k8s.io/http/request_count"). Name string `json:"name"` @@ -238,9 +223,6 @@ type AccessLogsConfig struct { // Global switch to enable or disable access logging. Enabled bool `json:"enabled"` - // The format of the logs (e.g., JSON, Text). - Format string `json:"format,omitempty"` - // Conditions for logging, allowing filtering to specific paths or events. Matches []MatchCondition `json:"matches,omitempty"` @@ -268,8 +250,8 @@ type MatchCondition struct { #### Tracing * **Sampling**: Supports probabilistic and parent-based sampling. -* **Propagation**: Explicitly configures propagation formats (W3C TraceContext defaults, option B3, Jaeger, etc.) * **Customization**: Allows appending custom tags/attributes to spans. +* **Propagation**: We assume the W3C TraceContext is used, this cannot be overridden. #### Metrics @@ -278,10 +260,8 @@ type MatchCondition struct { #### Logging -* **Flexible Formatting**: Supports both JSON and text formats for compatibility with standard log aggregation stacks. * **Smart Filtering**: Reduces noise and cost via CEL-based filtering, allowing logs to be generated only for specific events (e.g., 5xx errors, high latency, or critical paths). * **Custom Attributes**: Enables the extraction of specific headers and proxy metadata into log entries. -* **Sinks**: Defaults to standard container logging (stdout) with extensibility for OTLP or external ports. ## Comparison with Prior Art From d1f0564c370ae91a2578912d2f1fb1a54d5896a7 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 1 Apr 2026 18:43:41 -0700 Subject: [PATCH 16/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index c6aabf43..784de322 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -70,6 +70,7 @@ spec: # 1. Tracing Configuration tracing: + enabled: true provider: endpoint: "otel-collector.monitoring.svc:4317" samplingRate: @@ -85,8 +86,6 @@ spec: # 2. Metrics Configuration metrics: enabled: true - provider: - type: Prometheus overrides: - name: "gateway.networking.k8s.io/http/request_count" type: Counter @@ -97,9 +96,7 @@ spec: # 3. Access Logging accessLogs: enabled: true - format: JSON matches: # Conditional logging - - path: "/api/v1/sensitive" - cel: "response.code >= 500" # CEL-based filtering for errors fields: # Configure specific fields to include - "start_time" @@ -163,6 +160,10 @@ type TelemetryPolicySpec struct { // --- Tracing Types --- type TracingConfig struct { + + // Global switch to enable or disable tracing. + Enabled bool `json:"enabled"` + // Specifies the tracing backend. Includes type (e.g., "OTLP") and endpoint. Provider *TracingProvider `json:"provider,omitempty"` @@ -231,9 +232,6 @@ type AccessLogsConfig struct { } type MatchCondition struct { - // Path allows filtering to specific paths. - Path string `json:"path,omitempty"` - // CEL provides an expression for advanced filtering (e.g., matching response codes, headers). CEL string `json:"cel,omitempty"` } From 9fa26245d4fa13da045867e61fc5eeea14528b50 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 1 Apr 2026 18:54:12 -0700 Subject: [PATCH 17/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 45 ++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 784de322..478d8b9b 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -141,6 +141,10 @@ type TelemetryPolicy struct { metav1.ObjectMeta `json:"metadata,omitempty"` Spec TelemetryPolicySpec `json:"spec"` + + // status defines the observed state of TelemetryPolicy. + // +optional + Status TelemetryPolicyStatus `json:"status,omitempty"` } type TelemetryPolicySpec struct { @@ -235,6 +239,47 @@ type MatchCondition struct { // CEL provides an expression for advanced filtering (e.g., matching response codes, headers). CEL string `json:"cel,omitempty"` } + +// --- Policy Status --- + +// TelemetryPolicyStatus defines the observed state of TelemetryPolicy. +type TelemetryPolicyStatus struct { + // For Policy Status API conventions, see: + // https://gateway-api.sigs.k8s.io/geps/gep-713/#the-status-stanza-of-policy-objects + // + // Ancestors is a list of ancestor resources (usually Backend) that are + // associated with the policy, and the status of the policy with respect to + // each ancestor. When this policy attaches to a parent, the controller that + // manages the parent and the ancestors MUST add an entry to this list when + // the controller first sees the policy and SHOULD update the entry as + // appropriate when the relevant ancestor is modified. + // + // Note that choosing the relevant ancestor is left to the Policy designers; + // an important part of Policy design is designing the right object level at + // which to namespace this status. + // + // Note also that implementations MUST ONLY populate ancestor status for + // the Ancestor resources they are responsible for. Implementations MUST + // use the ControllerName field to uniquely identify the entries in this list + // that they are responsible for. + // + // Note that to achieve this, the list of PolicyAncestorStatus structs + // MUST be treated as a map with a composite key, made up of the AncestorRef + // and ControllerName fields combined. + // + // A maximum of 16 ancestors will be represented in this list. An empty list + // means the Policy is not relevant for any ancestors. + // + // If this slice is full, implementations MUST NOT add further entries. + // Instead they MUST consider the policy unimplementable and signal that + // on any related resources such as the ancestor that would be referenced + // here. + // + // +required + // +listType=atomic + // +kubebuilder:validation:MaxItems=16 + Ancestors []PolicyAncestorStatus `json:"ancestors"` +} ``` ### Alignment with Requirements From 35eb9453cebe73ae3b8080df3cb4546720ff8704 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 1 Apr 2026 19:11:54 -0700 Subject: [PATCH 18/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 478d8b9b..430ed00f 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -149,7 +149,7 @@ type TelemetryPolicy struct { type TelemetryPolicySpec struct { // Identifies the target resources (Gateway or Namespace) to which this policy attaches (GEP-713). - TargetRefs []TargetReference `json:"targetRefs"` + TargetRefs []NamespacedPolicyTargetReference `json:"targetRefs"` // Configuration for distributed tracing options. Tracing *TracingConfig `json:"tracing,omitempty"` From 8600d0bff2fdde70d53f925a9b4706e6e7777890 Mon Sep 17 00:00:00 2001 From: Georgi Khomeriki <3199233+gkhom@users.noreply.github.com> Date: Wed, 1 Apr 2026 19:32:48 -0700 Subject: [PATCH 19/19] Update 0069-TelemetryPolicy.md --- docs/proposals/0069-TelemetryPolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/0069-TelemetryPolicy.md b/docs/proposals/0069-TelemetryPolicy.md index 430ed00f..429f8538 100644 --- a/docs/proposals/0069-TelemetryPolicy.md +++ b/docs/proposals/0069-TelemetryPolicy.md @@ -292,7 +292,7 @@ type TelemetryPolicyStatus struct { #### Tracing -* **Sampling**: Supports probabilistic and parent-based sampling. +* **Sampling**: Trace sampling uses a probabilistic `samplingRate` for incoming requests. An optional `parentBasedSampling` configuration allows for a distinct sampling rate specifically for requests that are already part of a trace. * **Customization**: Allows appending custom tags/attributes to spans. * **Propagation**: We assume the W3C TraceContext is used, this cannot be overridden.