Skip to content

gep-4768: add TelemetryPolicy API proposal - #4872

Merged
kubernetes-prow[bot] merged 38 commits into
kubernetes-sigs:mainfrom
gkhom:main
Aug 18, 2026
Merged

kubernetes-prow[bot] merged 38 commits into
kubernetes-sigs:mainfrom
gkhom:main

Conversation

@gkhom

@gkhom gkhom commented May 17, 2026

Copy link
Copy Markdown
Contributor

What type of PR is this?

/kind gep

What this PR does / why we need it:

Added an initial proposal for the TelemetryPolicy API (gep-4768). This includes an example, the Go structs, and comparison with prior art. (See: #4768)

Does this PR introduce a user-facing change?:

NONE

@k8s-ci-robot k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/gep PRs related to Gateway Enhancement Proposal(GEP) do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels May 17, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: gkhom
Once this PR has been reviewed and has the lgtm label, please assign youngnick for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels May 17, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

Hi @gkhom. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@LiorLieberman

Copy link
Copy Markdown
Member

/ok-to-test
/cc @rikatz
/cc

@k8s-ci-robot k8s-ci-robot added the ok-to-test Indicates a non-member PR verified by an org member that is safe to test. label May 18, 2026
@k8s-ci-robot
k8s-ci-robot requested a review from rikatz May 18, 2026 14:19
@k8s-ci-robot k8s-ci-robot removed the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label May 18, 2026
Comment thread geps/gep-4768/index.md Outdated

# 1. Tracing Configuration
tracing:
mode: "On"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

the mode here is kind of a weird value. Usually we avoid to have bools or "wana be bools" (On/Off, True/False) and instead make them more explicit on Behavior (Disabled, PartiallyEnabled, FullyEnabled)

If we can only have On/Off, wouldn't it make more sense to say "if tracing is null, tracing should be disabled" instead?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

(btw this applies to every "Mode" defined here)

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.

The reason I added this explicit field is to allow implementations to define their own default behaviors. If we interpret a null/omitted block as "disabled", it would force "off-by-default" behavior for all implementations. For example, if a TelemetryPolicy is defined that only has explicit config for tracing, then it would imply that metrics and logs are disabled instead of the implementation's default. With the proposed schema we end up with the follow three distinct states:

  • Omitted (Null): No preference expressed, the implementation uses its native default.
  • Explicitly On: Ensure the feature is active.
  • Explicitly Off: Ensure the feature is inactive.

As an added bonus, the explicit field allows a feature to be disabled without having to delete complex configuration (e.g., field mappings or CEL expressions). The example demonstrates this in the accessLogs block.

Is it reasonable to allow implementations to maintain their own telemetry defaults? If so, I'm happy to rename the enum values to "enabled/disabled" if it helps.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think this is still arguable. Mode can imply lots of things, can be "Partial", can imply operating modes. I think the field name here should probably be reworked into something more explicit of the intent of it (tho tbh I don't have a better name now and I don't like enabled/disabled much as well). I need to think more on it

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 also find it challenging to come up with a better name for the field. Alternatively, we could indeed consider removing this field entirely. We would need to define the default behaviors in the absence of these blocks. For example, the defaults could be:

tracing: default disabled
tracing/parentBasedSampling: default disabled
metrics: default enabled
access logs: default enabled

The downside of this is that the defaults aren't consistent across the different blocks. Wdyt?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

let me try to put on a different way and you tell me if it makes sense:

  • a null configuration means "admin has no opinion, use the implementation defaults". We do not test conformance on it
  • a tracing configuration, with numerator=0 means "disabled sampling rate" so the admin is explicitly saying "I DO NOT WANT" telemetry.
  • same applies for parentBasedSampling
  • On the other hand, any of these options with a number bigger than 0 means "the admin has an opinion and wants to have this configuration"

Probably a similar approach can be applied to metrics, where if you set a configuration with an override that drop every metric, you are disabling the metrics.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Agreed on mode: On/Off being not ideal.

a tracing configuration, with numerator=0 means "disabled sampling rate" so the admin is explicitly saying "I DO NOT WANT" telemetry.

On this, I dont really like having a value as an indication of "disable it" this feels very indirect.

Whats the current state of the art WRT to defaults? do most implementation default to have tracing configs on or off by default?

The enum based approach is IMO better.

Why should not we have something simple like: "if TelemetryPolicy CRD exists and have tracing configs -- tracing configs are taken from this crd. If not, implementation does whatever their default is (whether its specific configs or OFF by default). I dont think we need to attempt standardizing what happens when this CRD is not applied in the cluster.

We can (and maybe should) support a modeDisabled enum though to standardize "how do I disable telemetry".

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.

It's better to not have "unspecified" have a meaning that could vary between implementations. We should be explicit.

So, if we need the default to be "whatever the implementation wants" (which I think is probably still arguable), then this should be an +optional Enum, with an ImplementationDefault value, that is the default if the field is unspecified.

I'd really prefer to have it disabled unless enabled, but I acknowledge that it's a breaking change and would almost certainly not be in user's best interests, so I think this is a good compromise.

Notably, having a default value supplied like that means that the field may get serialized with that value into etcd; this is very preferable in my mind, as it makes this ImplementationDefault mode extremely explicit.

Comment thread geps/gep-4768/index.md Outdated
# 3. Access Logs Configuration
accessLogs:
mode: "Off" # Explicitly disabled while keeping the configuration intact
matches: "response.code >= 500" # Conditional logging, CEL filtering for errors

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

honest question here: is CEL matching for logs something usually supported by OTEL exporters, or is this something specific from Istio that we are carrying?

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 don't think OTel exporters support this, but OTel collectors support the filterprocessor which is based on a "CEL-like" language: OTTL. It could be argued that if the collectors filter logs, the gateway doesn't need to support this. However, I believe that filtering at the source saves resources and not all deployments utilize a collector.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Oh I am not arguing against saving resource, but we need to think what happens for collectors that support a different type of filter:

https://github.com/haproxytech/haproxy-opentelemetry/blob/89ef0bc878e856cac2a2a6577bcfb16d5491a0cd/README-configuration#L462

maybe we need to say that filter support is by its own extended, but try to have a more common filter language (unless we can have a major agreement on every implementation on converting the CEL filtering to its own filtering, which I think will be harder)

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 agree that translating CEL into proxy-specific filter languages will be challenging for some implementations.

The Matches field is currently designated with Support: Implementation-specific. Implementations unable to natively evaluate or translate CEL would reject the policy with an UnsupportedField condition. Or would Extended support align better with Gateway API standards?

Do you think keeping CEL but strictly treating it as Extended/Implementation-specific is an acceptable compromise?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

yes it is, keeping as implementation specific, and then we can promote later to extended. But if we have a field that is implementation specific only, does it make sense to cover on this GEP now?

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Resolved
@sjberman

Copy link
Copy Markdown
Contributor

If it helps with some of this API design, here is the ObservabilityPolicy API used by NGINX Gateway Fabric to configure the nginx-otel module. It attaches to a Route.

NGINX supports setting span names and trace context as well, which I don't see in the proposed API.

In addition, we configure the exporter settings at the Gateway level in our NginxProxy API, which includes things like service.name attribute, export interval, batch size, and batch count.

Since we already support all of these fields, the new TelemetryPolicy would need to support them as well in some form before we would be able to migrate to it.

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Outdated

const (
// CustomAttributeTypeHeader extracts the value from an HTTP header.
CustomAttributeTypeHeader CustomAttributeType = "Header"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

can we be explicit of what can be added or not? I would expect that we are careful with things like "Authorization" headers and other sensitive headers.

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 think that the API should remain non-opinionated on this. There are use-cases in which even sensitive headers/values are required in telemetry.

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.

I think we should be clear: Implementations SHOULD NOT allow passing sensitive values without a very good reason, as logging or storing sensitive values is more often than not a security risk.

I'd prefer to start with MUST NOT, and loosen this to SHOULD NOT if we find specific use cases that need it. But I'd prefer to start with secure-by-default, and only loosen with big warnings and maybe an Extended feature for it, so that we don't automatically build CVEs into every implementation.

Comment thread geps/gep-4768/index.md Outdated
const (
// CustomAttributeTypeHeader extracts the value from an HTTP header.
CustomAttributeTypeHeader CustomAttributeType = "Header"
// CustomAttributeTypeMetadata extracts the value from proxy metadata or context.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

so, Metadata is a bit of a confusing concept in this context. I am worried we are making it very "Envoy" centric (unless @sjberman tells me he gets the concept of "metadata" here out of Nginx)

As we are leaning towards OTEL, I think it would be good to be more explicit on what each attribute means (eg.: https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/ ) and use some OTEL references here

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.

No concept of metadata in nginx.

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.

Yeah, I'm pretty strongly opposed to "fetch a key from metadata"; it's completely unstructured and completely nonportable.

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 agree, relying on metadata is likely not a good idea. I will update the proposal to use references to OTel attributes.

Comment thread geps/gep-4768/index.md Outdated
}

type TelemetryPolicySpec struct {
// Identifies the target gateways to which this policy attaches (GEP-713).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

we must be specific here that at least one target is required

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.

Made it explicit (with comment and validation) that at least one target must be present.

Comment thread geps/gep-4768/index.md Outdated
// Identifies the target gateways to which this policy attaches (GEP-713).
TargetRefs []NamespacedPolicyTargetReference `json:"targetRefs"`

// Configuration for distributed tracing options.

@rikatz rikatz May 18, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The comment must be more complete. Think on users using this API. We must write here what is tracing, what Gateway users will get from it.

This applies for every comment on every struct, I would recommend taking a look into https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#backendtlspolicy

Each API field must contain:

  • What is the field
  • What happens when a user configure that field (or in the absence of that field)
  • Are there specific conflicting options?
  • Anything else that may help users to use

Also, given this is a field documentation for implementations, you must consider:

  • What an implementation must know when considering that field? (does setting it has any caveat? Does the implementation needs to consider some condition status?)
  • What the permutation of possible values can cause that the implementation must care? (think on conformance tests)

Think on https://gateway-api.sigs.k8s.io/guides/api-design/. The documentation must be separated between user facing and implementation facing (when writing implementation/developers facing, use the tag <gateway:util:excludeFromCRD></gateway:util:excludeFromCRD>)

Also, when defining fields you must define what kind of support you expect for it. Eg.:

  • core - means that the field is required to be recognized by the implementation for this feature to work. eg.: targetRefs
  • extended - means that the feature/field should be implemented by implementations that claim its support, but are not mandatory for the whole feature. eg.: a telemetryPolicy may support tracing, or metrics, or accessLogs, but doesn't require all of them to work
  • implementationSpecific - We don't do conformance test, and a user using it knows they will not have portability between implementations. We should avoid this kind of support, and use only if strictly required on new apis. An example is my question about the cel matching for logs, as I don't think every implementation supports it

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

+1 defining support levels at this stage is very important. Also worth keeping in mind, everything in core and extended should be covered by conformance tests, otherwise it risks becoming implementation-specific anyway.

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've added a first round of documentation to the API definition, including support levels. The documentation can be more elaborate in defining semantics but I'll do that as a follow up once we roughly agree on the API structure.

Comment thread geps/gep-4768/index.md Outdated
tracing:
mode: "On"
provider:
endpoint: "otel-collector.monitoring.svc:4317"

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.

should probably use backendRef style API to align with other APIs

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

+1 otherwise we have to discuss again how to specify TLS, ... (as also mentioned in https://github.com/kubernetes-sigs/gateway-api/pull/4872/changes/BASE..084523a5d6aa69293ca1b9577fabdab8487ba0da#r3260666205)

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.

Updated the example and API struct to use backendRef.

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Outdated
// --- Metrics Types ---

type MetricsConfig struct {
// Mode explicitly controls if metric generation is enabled. Valid values are "On" or "Off".

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.

What does it mean to turn off metrics generation? It does not seem reasonable to entirely disable all metrics for an application

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.

It seems plausible to me that a user can gain sufficient insights from traces and/or access logs alone. Out of curiosity, why do you think metrics must always be enabled?

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.

Metrics are pull based which generally means they are quite a bit cheaper than logs/traces to enable without using. Obviously some cost to maintain.

For Envoy specifically there is no way to dynamically disable metrics so this API would not be implementable on ~50% of implementations.

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.

Fair point about Envoy's core stats engine being static, but I think that we can achieve dynamic disablement at the filter/logger level using the Runtime Discovery Service (RTDS).

I'm not an expert on this but I think it's possible to link the telemetry collection filters (or StatsAccessLogger instances) to a standard RuntimeFilter, the Gateway controller can dynamically enable or bypass metric recording via RTDS config updates. This way a restart should not be required just to toggle metric generation.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Do we have any usecase that requires metric disablement? I think that right now 100% of the proxies generate metrics, if so - I would argue no need to define metric disablement here

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.

Users often turn (some of) them off in istio/envoy for scale reasons. see https://github.com/howardjohn/gateway-api-bench#route-scale

Comment thread geps/gep-4768/index.md Outdated
Mode TelemetryMode `json:"mode,omitempty"`

// List of configurations to customize specific metric families.
Overrides []MetricOverride `json:"overrides,omitempty"`

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.

What does this actually do? Is it customizing an existing metric? adding a new one?

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.

Is this maybe trying to formalize relabeling? 🤔

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.

The intent is to customize an existing metric. It's quite common for users to require additional attributes/labels for metrics.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Is there any expectation for how this should be done? Realistically there are two (and a half) options:

  1. envoy/agentgateway/nginx or any other proxies support dynamic metric overrides (whether it is names, attributes or something else). I dont think thats the case (but could be wrong)

  2. Something augments those metrics on top of the proxy and does these overrides. And this something is the thing that prometheus should scrape.

  3. Some kind of config in a metric collector/scraper that does that after it scrapes the original metrics and before it ships it to the metric store

For #3 - we dont need to standardize in gateway-api cause this is a job of a metric collector

For #1 - I dont think its supported right now. But this would be the most logical expectation I would expect the CRD fields would be implemented if we were to add them.

For #2 I am not sure if everyone runs their proxy in some kind of an envelope that wraps it and is capable of doing that.

I do agree that adding attributes or standardizing metrics and/or schemas are useful, but maybe we should start by guiding what metrics proxies should export (is it OTEL? is it working with OTEL community to define proxy metrics, is it something like gateway.k8s.io/?) I'm not quite sure -- just throwing it out there

Comment thread geps/gep-4768/index.md Outdated
MetricAttributeTypeLiteral MetricAttributeType = "Literal"
)

type MetricAttribute struct {

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.

So we can add fields only right, not remove them?

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.

Indeed, the current API spec only allows additions. I do think that removal is useful as well. Do you think we should accommodate this in the first iteration? It could be as simple as adding a field: action: remove.

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Outdated
// This is required if Type is "Literal".
LiteralValue *string `json:"literalValue,omitempty"`

// StandardValue specifies a standard log property (e.g., "RequestStartTime", "Duration").

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.

Are these defined? or implementation specific?

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 think that these should indeed be defined in this proposal. I'll add an explicit list of supported values, mapping them to the relevant OTel SemConv attributes. Hopefully, this can substitute relying on metadata as well.

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Outdated
}

type TracingProvider struct {
Endpoint string `json:"endpoint,omitempty"`

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.

How about TLS options and custom headers, per #4775 (comment)

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.

Updated the API to use backendRef so that should cover the TLS options. Do we still need something separate for custom headers?

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.

I'm thinking from the perspective of NGINX, which supports setting custom headers in the requests to the exporter backend.

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've added support for custom headers in the TracingProvider.

Comment thread geps/gep-4768/index.md Outdated
LogFieldTypeStandard LogFieldType = "Standard"
)

type LogField struct {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

It's not clear to me what the fields LogField in the log represents, is it a JSON field for specifying additional key-value pairs?

How do you plan to support customization of nested JSON structures? These are commonly used in access logs, e.g., in the Airlock Microgateway we use the Elastic Common Schema (ECS).

Since access logs tend to be highly implementation-specific, IMO a format string or an extension point is probably the best approach here.

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.

The LogField struct is indeed intended to specify key-value pairs for the access log output. For nested JSON structures like ECS, we can support dot-notation (e.g., user.id) in the name field, which implementations can then expand into structured objects during serialization.

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.

I believe dot-notation in a flat field ({"my.key": "bar"}) is both common and strictly required in OTEL semconv. So uplifting that into structured objects doesn't seem great

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.

Thanks, I overlooked that. To clean this up, I split the config into two separate structs:

  • Metrics & Traces (Attribute): Uses a single string name for standard flat key-value attributes.
  • Access logs (LogField): Uses a path list (containing path segments) to build nested JSON logs. Individual segments can contain dots that will be preserved verbatim. For example:
    • path: ["mcp.method"] maps to a flat key containing dots: {"mcp.method": "<value>"}.
    • path: ["http", "request", "start_time"] maps to a standard nested structure: {"http": {"request": {"start_time": "<value>"}}}.

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Outdated
// Identifies the target gateways to which this policy attaches (GEP-713).
TargetRefs []NamespacedPolicyTargetReference `json:"targetRefs"`

// Configuration for distributed tracing options.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

+1 defining support levels at this stage is very important. Also worth keeping in mind, everything in core and extended should be covered by conformance tests, otherwise it risks becoming implementation-specific anyway.

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Resolved

@robscott robscott left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks @gkhom! A few more tiny nits, otherwise LGTM.

Comment thread geps/gep-4768/index.md Outdated
// (i.e., as a span tag).
//
// +required
Name string `json:"name"`

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

v1.HTTPHeaderName would be appropriate for the HeaderName field below. Recommend defining a net new type for this, here's what AI recommends (which also seems reasonable to me):

// AttributeName defines the key of a span attribute or tag.
//
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=256
// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_.:/-]+$`
type AttributeName string

Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Resolved
Comment thread geps/gep-4768/index.md Outdated
Comment on lines +535 to +537
2. **Attribute Type Handling and Failure Modes**:
How should attribute data types (such as boolean, integer, or string) be handled and preserved when emitting custom span attributes or mapping dynamic header values?
Should an optional field (e.g., `valueType`) be added to the `Attribute` struct to allow explicitly specifying the output type for custom attribute keys, while relying on OpenTelemetry Semantic Conventions for standard keys?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

That makes sense. We can add this in the future if needed. In the meantime it may make sense to move this to "potential future additions" instead of "open questions" so it's not blocking the proposal from graduating to experimental.

@rikatz

rikatz commented Aug 17, 2026

Copy link
Copy Markdown
Member

/label tide/merge-method-squash

@kubernetes-prow kubernetes-prow Bot added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Aug 17, 2026
gkhom and others added 2 commits August 17, 2026 15:57
Co-authored-by: Rob Scott <rob.scott87@gmail.com>
@rikatz

rikatz commented Aug 17, 2026

Copy link
Copy Markdown
Member

/ok-to-test
/hold cancel

@kubernetes-prow kubernetes-prow Bot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 17, 2026
@kubernetes-prow kubernetes-prow Bot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 17, 2026
@robscott

Copy link
Copy Markdown
Member

Thanks @gkhom!

/lgtm

@kubernetes-prow kubernetes-prow Bot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 17, 2026

@snorwin snorwin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I reviewed all the changes again and overall it looks good to me to proceed forward. I'm especially looking forward to the conformance tests, I think we should really make sure that if this feature ends up in 1.7 as experimental, the conformance tests are already implemented, or at least some of them.

@gkhom thanks for the effort you put into this, really appreciated.

/lgtm

@kubernetes-prow

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: gkhom, rikatz, robscott, snorwin

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@rikatz

rikatz commented Aug 18, 2026

Copy link
Copy Markdown
Member

/ok-to-test
/hold cancel

@kubernetes-prow kubernetes-prow Bot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 18, 2026
@kubernetes-prow
kubernetes-prow Bot merged commit 96e4654 into kubernetes-sigs:main Aug 18, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/gep PRs related to Gateway Enhancement Proposal(GEP) lgtm "Looks good to me", indicates that a PR is ready to be merged. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. release-note-none Denotes a PR that doesn't merit a release note. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges.

Projects

None yet

Development

Successfully merging this pull request may close these issues.