agentic-dev/docs/library-decisions/2026-05-14-@opentelemetry/semantic-conventions.md

package, version, tier, decision, date, deciders, adr, filter-results, verification-commands, accepted-cves

package	version	tier	decision	date	deciders	adr	filter-results	verification-commands	accepted-cves
@opentelemetry/semantic-conventions	^1.27.0	core	approved	2026-05-14	Danijel Martinek	adr-017	license types maintenance boundary-fit shadow-check eu-residency cve-scan named-consumer socketRisk Apache-2.0 native active pass pass n/a clean pass clean	npm view @opentelemetry/semantic-conventions license npm view @opentelemetry/semantic-conventions version pnpm audit --audit-level=moderate

Filter: license

npm view @opentelemetry/semantic-conventions license returns Apache-2.0. Apache-2.0 is on the allowlist.

Filter: types

@opentelemetry/semantic-conventions is authored in TypeScript and ships its own .d.ts declaration files. No separate @types/ package is needed.

Filter: maintenance

Actively maintained by the OpenTelemetry community. The 1.27.x line is on the stable 1.x track. Semantic conventions are a CNCF specification that evolves across OTel SDK releases.

Filter: boundary-fit

ADR-017 §8 restricts @opentelemetry/semantic-conventions to **/instrumentation/otel/** and app init paths. Attribute name constants from this package are used in core-shared/instrumentation/otel/ to label span attributes consistently (e.g., SEMATTRS_DB_SYSTEM, SEMATTRS_HTTP_METHOD). Feature packages never import it directly.

Filter: shadow-check

@opentelemetry/semantic-conventions is the canonical OTel attribute name registry. No competing attribute-naming package is present in the workspace. Using this package prevents hard-coded string attribute names that diverge from the OTel spec.

Filter: eu-residency

@opentelemetry/semantic-conventions is a pure constants package with no network communication or data transmission. EU residency does not apply.

Filter: cve-scan

pnpm audit --audit-level=moderate reports no advisories against @opentelemetry/semantic-conventions at the time of this trace.

Filter: named-consumer

packages/core-shared/src/instrumentation/otel/ uses semantic convention constants to name span attributes on HTTP instrumentation config, pg instrumentation config, and custom spans. Consistent attribute naming enables Sentry and any future backend to parse spans correctly.

Prompt: replaces

Hard-coded string attribute names (e.g., "http.method", "db.system") that would otherwise be scattered across instrumentation code without a canonical reference. Semantic conventions provide typed, versioned constants with IDE autocompletion and forwards-compatibility guarantees.

Prompt: migration-cost-out

Low. @opentelemetry/semantic-conventions is a constants-only package. Removing it means replacing constant references with hard-coded strings in core-shared instrumentation code — a mechanical change with no behavioral impact.

Prompt: alternatives-considered

1. Hard-coded string constants — Define attribute names as local const values. Rejected: diverges from the OTel specification over time as attributes are renamed or deprecated; loses IDE-navigable documentation links.
2. No attribute naming standard — Each developer picks attribute names ad-hoc. Rejected: breaks Sentry query grouping, dashboard filters, and any backend that relies on spec-compliant attribute names for parsing.

See ADR-017 for the full decision rationale.