-
Notifications
You must be signed in to change notification settings - Fork 733
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Semconv 1.25 #4690
base: main
Are you sure you want to change the base?
Semconv 1.25 #4690
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added some quick comments to explain some of my thought process
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Template is a lot smaller now because I removed all the namespaced stuff that will never be updated and is considered deprecated.
packages/opentelemetry-semantic-conventions/src/trace/SemanticAttributes.ts
Show resolved
Hide resolved
* | ||
* Note: Total CPU time consumed by the specific container on all available CPU cores. | ||
* | ||
* @experimental this metric is experimental and is subject to change in minor releases of `@opentelemetry/semantic-conventions`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Everything in this file is experimental
@@ -1 +1,2 @@ | |||
opentelemetry-specification/ | |||
semantic-conventions/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added a new ignore. Kept the old one since a lot of people have already checked it out and it isn't hurting anything
* | ||
* @experimental this metric is experimental and is subject to change in minor releases of `@opentelemetry/semantic-conventions`. | ||
*/ | ||
export const METRIC_CONTAINER_CPU_TIME = 'container.cpu.time'; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added metric names with METRIC_
prefix
packages/opentelemetry-semantic-conventions/src/experimental.ts
Outdated
Show resolved
Hide resolved
/cc @trentm @JamieDanielson since you seemed interested in this /cc @MSNev since you have done the most work on this recently |
I'll take a while to review this. I'm still trying to grok the generation, the semantic-conventions/model vs schemas/... subdirs, etc. Some early Qs/thoughts:
Correctness Qs:
* @deprecated use ATTR_HTTP_CLIENT_IP
*/
export const SEMATTRS_HTTP_CLIENT_IP = TMP_HTTP_CLIENT_IP; Same for |
The
Can the description (is that the "brief" yaml field?) of the value be used, instead? |
Yes I did consider that and I still would consider it if we want to go that route. It is my understanding that the semconv has decided to use a registry of unique attributes that can be applied to any signal or resource so there is no reason to differentiate them. I only kept the ATTR and METRIC prefix just to make it easier to find the value you want when autocompleting and not get confused.
I'm actually sure they're NOT all there. The deprecated.yaml didn't exist when many of these were removed and they weren't all added back. I left all the old versions in the file they were already in, so it isn't a breaking change, but I am going to add the missing attributes to the registry anyway (see open-telemetry/semantic-conventions#1025)
Good catch. I'll update the PR |
@trentm what about this? |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #4690 +/- ##
=======================================
Coverage 91.04% 91.04%
=======================================
Files 89 89
Lines 1954 1954
Branches 416 416
=======================================
Hits 1779 1779
Misses 175 175 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So far this is looking really great, thanks @dyladan and thanks @trentm for the review so far.
I like ATTR
better than SEMATTRS
and SEMRESATTRS
and wish I had realized this sooner and commented on the original PR that introduced them. I'm not clear what the full benefit is of having those other prefixes, although it may have been more relevant before they were in the global registry.
I only kept the ATTR and METRIC prefix just to make it easier to find the value you want when autocompleting and not get confused.
I'm not sure I understand the value of having ATTR
prefix for attributes but no prefix for values. In that case I'd think they could be prefixed as well, or prefix neither.
🤔 The benefit of keeping experimental attributes in /experimental subdirectory is that we are making it very explicit that it is an experimental attribute. I guess the downside is when the experimental attribute becomes stable, the consumer of that would have to update their code when they upgrade packages? |
Exactly. Previously there was some chance (although probably it wouldn't have happened) that the same attribute could have been defined for different signals. I think the most reasonable way this could have happened would be for an attribute to have bounded specific values for metrics to control cardinality, but be unbounded for other signals or resources.
The way we have it in this PR values have a postfix (actually an infix between the enum name and the value name). It provides separation between the enum name and the value name so it is distinguishable easily. For example, |
I guess Java has a separate package for experimental attributes - there's a semconv in instrumentation-api, and a semconv in instrumentation-api-incubator. Python also has semconv in incubating separate from semconv stable. Go seems to have it all in one. |
This is the definition of experimental... It also would force users to at least consider if they need to make a change. If the semconv attributes you're using change it might be good to force our users to acknowledge that by changing to the stable export. If they can get all from a single export they may never notice if something is renamed/deprecated.
I think a single package with multiple entry points is roughly equivalent to having separate packages and less overhead. Go has all in one but they export each version separately so you have to do something to get the new semconv version. |
My understanding of the OTel Java team's recommendations/requirements is that they do not allow a stable instrumentation package to have a dependency on the I guess we could get the equivalent by either (a) never using the "../experimental" entry point in stable instrumentation packages, or (b) pinning the
Agreed.
This PR beat me to an attempt to update the semconv package. FWIW, I had been considering having separate entry points for each semconv version. See #4572 (comment) |
Nice. That looks good.
My soft vote is for no prefixes. The way I thinking/expecting developers to use semconv values was to (a) have a semantic-conventions document open (e.g. https://opentelemetry.io/docs/specs/semconv/http/http-metrics/) and see a string (e.g. IIUC, autocomplete will show Another small reason is that I like the shorter names in code. This is a soft vote though. I don't have a very strong reaction to |
I like the |
@MSNev what would you think of combining export const ATTR_LOG_IOSTREAM = 'log.iostream';
export const ENUM_LOG_IOSTREAM_VALUES_STDOUT = 'stdout';
export const ENUM_LOG_IOSTREAM_VALUES_STDERR = 'stderr'; edit: I like someone's suggestion above to singular |
Reverting to draft while we wait on a resolution from open-telemetry/semantic-conventions#1031 |
Interestingly, perhaps, I just noticed that the recently updated Python semconv generation appends - id: request.header
stability: stable
type: template[string[]]
brief: >
HTTP request headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values. Is |
Yeah we're actually ignoring those for now. I was going to add them in a follow-up because they are handled differently |
@MSNev does the limitation on attribute values not being the same as attribute namespaces mentioned by @lmolkova in open-telemetry/semantic-conventions#1064 ease your concerns with enum names? There should be no collision. |
If we want to go with the changing the names of the values to full screaming snake case rather than the existing so export const ATTR_LOG_IOSTREAM = 'log.iostream';
export const LOGIOSTREAM_STDOUT = 'stdout';
export const LOGIOSTREAM_STDERR = 'stderr'; becomes export const ATTR_LOG_IOSTREAM = 'log.iostream';
export const VAL_LOG_IO_STREAM_STDOUT = 'stdout';
export const VAL_LOG_IO_STREAM_STDERR = 'stderr'; This way there would always be zero chance of any conflict, vs the infix option. This would also work for whatever the outcome of the Personally, I prefer the existing (but I guess I'm a little biased as that was my original choice) to convert the CamelCased values classes to the combination to avoid clashes 😀 |
General comment on this from in the description
This was actually always the goal, the namespace "fun" was just part of the stepping stones to move forward and to try and keep the generated package as small as possible without just duplicating the string. |
I decided to just duplicate it. I think not long from now we'll go 2.0 and remove the namespace fun entirely. |
Comparing this to other options: export const ATTR_LOG_IOSTREAM = 'log.iostream';
export const LOG_IOSTREAM_VALUES_STDOUT = 'stdout';
export const LOG_IOSTREAM_VALUES_STDERR = 'stderr'; or perhaps singular export const ATTR_LOG_IOSTREAM = 'log.iostream';
export const LOG_IOSTREAM_VALUE_STDOUT = 'stdout';
export const LOG_IOSTREAM_VALUE_STDERR = 'stderr'; I can understand the desire for a prefix (e.g. The infix export const VAL_HTTP_FLAVOR_HTTP1_0 = '1.0' as const;
export const VAL_HTTP_FLAVOR_HTTP1_1 = '1.1' as const;
export const VAL_HTTP_FLAVOR_HTTP2_0 = '2.0' as const; I have a slight preference for infix |
I tend to agree with you |
…elemetry-js into semconv-1.25
@dyladan Yah, I don't hate Using "VALUE" in an auto-complete UI to filter on the enum values suffices, so having Part of me still wants to drop the My vote is for:
but at this point I'm fine with almost any of the variants on this. |
This is a big PR but most of it is autogenerated. Below is a list of changes:
experimental.ts
andstable.ts
so we can export separately in the future if required@experimental
jsdoc tagSEMRESATTRS_
andRESATTRS_
to justATTR_
for attributesMETRIC_
prefix2.0
if we ever release oneNotes:
http.request.header.<key>
for now. It's not clear how we can/should support them and until we make a decision i'd leave them out (they were excluded/didn't exist before)Questions:
For the main exportmain export is stable only with backwards compatibility for previous releases.import {} from '@opentelemetry/semantic-conventions'
should ALL semconv be exported experimental and stable, or should only the stable be exported and experimental would be imported from@opentelemetry/semantic-conventions/experimental
?Example: this is what it would look like to update the utils.ts file in the http instrumentation.