Semantic Conventions Update Options

[dyladan]

trafficstars

This is to document each of the potential solutions we have discussed to update our semantic conventions

Option 1: package.json entry points

example: https://github.com/open-telemetry/opentelemetry-js/pull/4770

This option involves adding an entry point for each semconv version. The top level export would export stable attributes, and all experimental attributes would be hidden under a version-specific entrypoint.

import { SOME_EXPERIMENTAL_ATTR } from '@opentelemetry/semantic-conventions/1.26'
import { SOME_STABLE_ATTR } from '@opentelemetry/semantic-conventions'

Cons:

• Likely massive installation size eventually

Option 2: single semconv version per release

This option involves publishing a new semconv package and version-locking it with the upstream semconv. Each version would contain only its generated attributes.

{
   "dependencies": {
      "@opentelemetry/semconv-1_26": "npm:@opentelemetry/[email protected]",
      "@opentelemetry/semconv-1_25": "npm:@opentelemetry/[email protected]"
   }
}

import { SOME_ATTR } from '@opentelemetry/semconv-1_26'
import { SOME_OTHER_ATTR } from '@opentelemetry/semconv-1_25'

Cons:

• Versioning might be weird
• Users have to do weird stuff in their package.json

Option 2.1: Release a new package for each semconv version with version in name

This is similar to the above but we actually bake the semconv version directly into the name of the package so the user doesn't have to mess around with package.json renames. We would not keep old versions in the repo since they would never be updated. If they do need to be updated we would have to resurrect them from git history.

{
   "dependencies": {
      "@opentelemetry/semconv": "^1.26.0",
      "@opentelemetry/semconv-1_26": "^1.0.0",
      "@opentelemetry/semconv-1_25": "^1.0.0"
   }
}

import { STABLE_ATTR } from '@opentelemetry/semconv'
import { SOME_EXPERIMENTAL_ATTR } from '@opentelemetry/semconv-1_26'
import { SOME_OLD_ATTR } from '@opentelemetry/semconv-1_25'

Option 3: use stable/experimental package.json entrypoints

Example: https://github.com/open-telemetry/opentelemetry-js/pull/4690

This involves using package.json entrypoints to export experimental attributes explicitly. Top level would only include stable attributes. Deprecated attributes are included with @deprecated tags for backwards compatibility.

import { STABLE_ATTR } from '@opentelemetry/semantic-conventions'
import { SOME_EXPERIMENTAL_ATTR } from '@opentelemetry/semantic-conventions/experimental'

Other options lightning round

These options were discussed but nobody seemed to jump at them and there wasn't much discussion

• CLI tool that generates a telemetry.js file for end users
• types-only devDependency package that compiles to nothing
• manually maintain deprecated attributes in a separate file