Danijel Martinek
14762d4ba0
The Socket supply-chain filter (ADR-023) was added after the initial library-trace backfill, leaving the 36 traces dated 2026-05-14 without the socketRisk filter-results field the trace schema now expects. Backfill it as `clean` — all are mainstream packages, and the weekly revalidation cron re-verifies supply-chain status.
88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
---
|
|
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.
|