Open JamieDanielson opened 7 months ago
@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.
~Interesting, in https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2089#discussion_r1568777128 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
:
@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 https://github.com/open-telemetry/opentelemetry-js/issues/4235#issuecomment-1893611469" is motivated by. Am I correct in assuming this requirement is gone now that all deprecated attributes are available?
Take a peek here https://github.com/open-telemetry/opentelemetry-js/pull/4690
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:
@opentelemetry/semantic-conventions/1_7
, then work through upgrade semconv usage in each package as appropriatePros:
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:
@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): https://github.com/open-telemetry/semantic-conventions/issues/551#issuecomment-1834447604 and a comment above from a .NET perspective, argues in favour of separate entry-points for each semconv version, FWIW.
Am I correct in assuming this requirement is gone now that all deprecated attributes are available?
We talked about this in the SIG meeting but for posterity, yes, the deprecated attributes being available to us in the latest semantic conventions removes the need to have multiple packages.
Hi @JamieDanielson thank you for driving this important topic! If I see correctly, there is more than a year of delay of adopting sematic conventions. For building and role out contents on top of changed fields, an envisioned time of arrival would be great to know!
@juergen-walter https://github.com/open-telemetry/opentelemetry-js/pull/4690 merged yesterday, so the next release from this repo will include a semantic-conventions package with constants from the latest Sem Conv version. Now we need to work through each package, as appropriate, an update their usage for the newer semconv version.
@juergen-walter the new semantic conventions package v1.27 is now released
Current Status
Current (latest) package of
@opentelemetry/semantic-conventions
uses semconv version v1.7.0, as seen inscripts/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
@opentelemetry/semantic-conventions-1_7
), and update imports everywhere, as suggested on #4235~METRIC_
prefixopentelemetry.io
docs for potential changes neededNote: Import
@opentelemetry/semantic-conventions
for stable semantic conventions. Import@opentelemetry/semantic-conventions/incubating
for all semantic conventions, stable and unstable.