agentic-dev/semantic-conventions.md at 3d52f2de85abc9a4e88aceacf4622df8b3440e4a

Template

Files

Danijel Martinek f77e6ea881 chore(template): clean-slate template snapshot from bb4a0c7

Curated, product-agnostic snapshot of the post-story-04 tree: demo
content deleted, auth-only reference feature, web-next shell, all gates
green. Product-specific docs, ADRs 027-029, PRDs/epics/archive, editor
library traces, and product naming are curated out; generic template
repairs (coverage provider devDeps, root test:coverage script, live
lint fixes, root-only release-please) are kept. See TEMPLATE.md for
provenance, curation list, and usage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK

2026-07-12 20:40:54 +02:00

3.5 KiB

Raw Blame History

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

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

3.5 KiB Raw Blame History