Repository navigation
gep-5253: Standardized Attribute Dictionary - #5256
Conversation
|
This issue is currently awaiting triage. If Gateway API community members determine this is a relevant issue, they will accept it by applying the The DetailsInstructions 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. |
|
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 Regular contributors should join the org to skip this step. Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions 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. |
|
|
||
| ## 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`. |
There was a problem hiding this comment.
Isn't L40 saying you MUST NOT? or is "command string" something different than "keys outside the dictionary"?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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?
There was a problem hiding this comment.
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 prefixI 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 .)
There was a problem hiding this comment.
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"]
There was a problem hiding this comment.
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.
|
/ok-to-test I have one comment about just fixing metadata, and then this can be lgtm'd |
|
[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 DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
LGTM once @robscott's last change is done. |
Co-authored-by: Rob Scott <rob.scott87@gmail.com>
|
/lgtm |
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?:
Was AI used in preparing this PR?
/label ail/2