Skip to content

gep-5253: Standardized Attribute Dictionary - #5256

Merged
kubernetes-prow[bot] merged 7 commits into
kubernetes-sigs:mainfrom
gkhom:main
Sep 23, 2026
Merged

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

Conversation

@gkhom

@gkhom gkhom commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

What type of PR is this?

/kind gep

What this PR does / why we need it:
Proposal for a standardized dictionary of attributes based on OpenTelemetry Semantic Conventions.

Which issue(s) this PR fixes:

Fixes #5253

Does this PR introduce a user-facing change?:

NONE

Was AI used in preparing this PR?

/label ail/2

@kubernetes-prow kubernetes-prow Bot added release-note-none Denotes a PR that doesn't merit a release note. kind/gep PRs related to Gateway Enhancement Proposal(GEP) ail/2 Categorizes a PR as having AI Influence Level 2 (major AI augmentation) needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Sep 14, 2026
@kubernetes-prow

Copy link
Copy Markdown

This issue is currently awaiting triage.

If Gateway API community members determine this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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.

@kubernetes-prow kubernetes-prow Bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-priority needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 14, 2026
@kubernetes-prow

Copy link
Copy Markdown

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.

@kubernetes-prow kubernetes-prow Bot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Sep 14, 2026
Comment thread geps/gep-5253/index.md Outdated

## Attributes outside the dictionary

An API MAY permit keys outside the dictionary. Such keys carry no portability guarantee and SHOULD be documented as implementation-specific. Such keys MUST NOT collide with the OTel namespaces the dictionary has adopted. Vendor or organization keys MUST be namespaced, e.g. `example.com/tenant`.

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.

Isn't L40 saying you MUST NOT? or is "command string" something different than "keys outside the dictionary"?

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 for flagging! I went back and forth whether keys outside the dictionary should be allowed. I settled on the posture that it should be allowed so long as it's explicitly marked as implementation-specific. Otherwise, the stability requirement for OTel attributes makes things perhaps too restrictive for implementations. Would love some feedback on this. In the meantime, I will update L40 to remain consistent with L103.

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.

We discussed this topic in yesterday's community meeting and the guidance was to allow non-dictionary keys but they must be domain-prefixed. For example, acme.com/mcp.client.operation.duration. Additionally, if Gateway API resources have a need to use keys outside of the dictionary they must be prefixed with unstable/ (or something similar). I will update the PR accordingly.

/cc @rikatz @youngnick

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 we planning to use these dictionaries in expression languages (CEL, presumably)? or only as plain string references?

if in expression languages I don't think you can do a prefix like this

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.

Great point, ideally the standard would not exclude usage in expression languages.

How about reverse-domain dot notation as a prefix? This would actually be more aligned with OTel's naming conventions:

com.acme.mcp.client.operation.duration
io.k8s.gateway.unstable.http.request.header

Wdyt?

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.

Thanks for clarifying @howardjohn.

Yeah, okay, I think we're just going to have to do option 3 and see what happens. But I agree with @rikatz that we need to make the contract clear - if an implementation does stuff in the global namespace (which is all we will have), and that messes that implementation up later, that's on the implementation to fix, not a concern for Gateway API.

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.

@howardjohn @gkhom for the sake of we progressing, are we all on the same page for Option 3 then, with an explicit statement about the risk of an implementation using something not defined on the dictionary that can become promoted later?

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 am good with 3 but am wondering if we want some nuance in "Expression language" vs "Emum". To be explicit i mean:

expressionLanguage: `k8s.request.header["my-header"] == my.vendor.field` # Per option 3, we can use specific vendor fields

enum:
  fieldName: k8s.request.url # Note: this is problematic since 
  otherFieldName: example.com/my.vendor.field # here i don't have a problem with a prefix

I would also note that enum fields (which I think are present in Telemetry last I looked) are somewhat problematic if I want to reference k8s.request.header["my-header"] (note header names can have a .)

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 maintaining uniformity regarding prefixes is preferable, so my vote goes to option 3 for both enums and expressions.

But the syntax could be different between the two cases:

For enums: http.request.header.my-header
For expressions: http.request.header["my-header"]

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 updated the PR to reflect this discussion. Keys outside the dictionary are allowed without a mandatory prefix and mentioned the non-portability implications. PTAL.

Comment thread geps/gep-5253/index.md Resolved
Comment thread geps/gep-5253/metadata.yaml Resolved
@rikatz

rikatz commented Sep 22, 2026

Copy link
Copy Markdown
Member

/ok-to-test
/approve
this looks great, thanks @gkhom

I have one comment about just fixing metadata, and then this can be lgtm'd
thanks

@kubernetes-prow kubernetes-prow Bot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. approved Indicates a PR has been approved by an approver from all required OWNERS files. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 22, 2026

@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!

/approve

Comment thread geps/gep-5253/index.md Resolved
@kubernetes-prow

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

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

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

@youngnick

Copy link
Copy Markdown
Contributor

LGTM once @robscott's last change is done.

gkhom and others added 2 commits September 23, 2026 08:17
Co-authored-by: Rob Scott <rob.scott87@gmail.com>
@rikatz

rikatz commented Sep 23, 2026

Copy link
Copy Markdown
Member

/lgtm
/hold cancel
Thanks!

@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 Sep 23, 2026
@kubernetes-prow kubernetes-prow Bot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 23, 2026
@kubernetes-prow
kubernetes-prow Bot merged commit 47f91b7 into kubernetes-sigs:main Sep 23, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ail/2 Categorizes a PR as having AI Influence Level 2 (major AI augmentation) 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. needs-priority needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. 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/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Standardized Attribute Dictionary (Memorandum)

5 participants