Initial commit

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

@@ -0,0 +1,87 @@
+---
+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
+  socketRisk: clean
+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.