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

## Filter: license

<!-- Result: Apache-2.0 -->

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

## Filter: types

<!-- Result: native -->

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

## Filter: maintenance

<!-- Result: active -->

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

<!-- Result: pass -->

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

<!-- Result: pass -->

`@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

<!-- Result: n/a -->

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

## Filter: cve-scan

<!-- Result: clean -->

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

## Filter: named-consumer

<!-- Result: pass -->

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