Semantic Convention Update: Tracking Issue

[JamieDanielson]

Current Status

Current (latest) package of @opentelemetry/semantic-conventions uses semconv version v1.7.0, as seen in scripts/semconv/generate.sh.

There are breaking changes in semantic conventions over time, especially prominent in v1.21 with stabilized http attributes, so we want to update in a way that minimizes impact on end users and offers the environment variable option OTEL_SEMCONV_STABILITY_OPT_IN to allow specifying which attributes to use. See schema for 1.23.1 here that shows changes over time.

Steps required for semantic convention update

• Update usage of semantic conventions to new exported strings opentelemetry-js-contrib#2025
• Update usage of semantic conventions to new exported strings #4567
• Document instrumentation semantic conventions opentelemetry-js-contrib#1778
• Make copy of existing semantic conventions by adding suffix 1_7 (@opentelemetry/semantic-conventions-1_7), and update imports everywhere, as suggested on #4235
• Separate publishing of semantic conventions for more control over version #4878
• Generate new semantic conventions. Use weaver to generate latest semconv 1.27 #4690
• Make decision on decide on advice for use of *unstable* semconv consts: copy or pin dep #5182
• Implement stable http semantic conventions #4897
• Use updated attributes with ATTR prefix in all packages #4896
• Use updated semantic-conventions pkg exports with ATTR_ prefix in all packages opentelemetry-js-contrib#2377
• update metric names to semconv METRIC_* exports #5956
• review tables in READMEs for potential changes needed
• review opentelemetry.io docs for potential changes needed: Update JS docs to stable semconv attribute names opentelemetry.io#8676
• update current status in https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/semconv-stable-http-and-database.md

Note: Import @opentelemetry/semantic-conventions for stable semantic conventions. Import @opentelemetry/semantic-conventions/incubating for all semantic conventions, stable and unstable.

[JamieDanielson]

@MSNev @pichlermarc I created this issue based on our conversation in the SIG meeting to help track the work required to update semantic conventions in otel-js. I believe the first and last few items here are generally uncontroversial, but I wanted to confirm the appropriate step is listed for keeping old semantic convention version intact.

Some languages have a subdirectory of every semconv version as mentioned here. At some point we've also talked about rolling our own that essentially just adds the new attributes into new files to be additive to the existing package, instead of keeping whole packages for each version. Curious for feedback on the approach we want to take.

[trentm]

Interesting, in open-telemetry/opentelemetry-js-contrib#2089 (comment) seemk got the impression that because SemanticAttributes usage is deprecated, they should turn to defining the attributes locally.
(Update: I misread the code. The PR is not defining semconv constants locally.)

I think a couple things could be improved in @opentelemetry/semantic-conventions:

• The "you shoud use the individual exported constants SemanticAttributes_XXXXX" prose is out of date, I think.
• The README still shows deprecated usage.

[dyladan]

@JamieDanielson i'm working on updating the semconv. I'm not clear what the action item "Make copy of existing semantic conventions by adding suffix 1_7 (@opentelemetry/semantic-conventions-1_7), and update imports everywhere, as suggested on #4235 (comment)" is motivated by. Am I correct in assuming this requirement is gone now that all deprecated attributes are available?

[dyladan]

Take a peek here #4690

[trentm]

Note: I'm not strongly advocating this option over Dan's option in #4690 unless others think it worthwhile.

Dan's PR beat me to an attempt to update the semconv package. I had been considering a semconv package that had separate entry points for each semconv version -- somewhat similar to what OTel Go is doing. E.g.:

import { HTTP_METHOD } from '@opentelemetry/semantic-conventions/1_20';
import { HTTP_REQUEST_METHOD } from '@opentelemetry/semantic-conventions/1_21';

The migration path would be:

• freeze '@opentelemetry/semantic-conventions' at the old 1.7 version, deprecate its usage
• move our instrs to use @opentelemetry/semantic-conventions/1_7, then work through upgrade semconv usage in each package as appropriate
• in 2.0, remove ability to use the top-level entry point, i.e. must use a specific version
• periodically add new entry points for new https://github.com/open-telemetry/semantic-conventions/tree/main/schemas versions

Pros:

• I like that instrumentation code needs to be explicit about what SemConv version it is written for.
• Having a single schemaUrl export (for usage in instrumentationScope to explicitly state the semconv version being used by an instrumentation) would be cleaner. (With a single @opentelemetry/semantic-conventions entry point, the package would want to export a schemaUrl value for each version, e.g. const SCHEMA_URL_V1_25_0 = ... something like what Java is doing.)

Cons:

• Someone would have to do the generator work. Dan's already mostly done the work for the "all attributes, including deprecated ones, in the top-level entry point".
• Without some effort on reducing duplication and with a number of semconv version entry-points the @opentelemetry/semantic-conventions package might get quite big to install. (Note: this wouldn't be an issue for tree-shaking minifying builds, just a size increate for npm install-time.)

Update (2024-05-23): open-telemetry/semantic-conventions#551 (comment) and a comment above from a .NET perspective, argues in favour of separate entry-points for each semconv version, FWIW.