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
• Generate new semantic conventions in scripts/semconv. In addition to the change in SPEC_VERSION, this will require further changes to repos and directories as the source files for semantic conventions migrated from open-telemetry/opentelemetry-specification to open-telemetry/semantic-conventions, and directories updated as well. For example, trace/http.yaml is now model/trace/http.yaml.
• Add environment variable option OTEL_SEMCONV_STABILITY_OPT_IN that includes http and http/dup options as suggested in the Migration Plan.
• Update instrumentation packages to use new environment variable and emit appropriate attributes

[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.