fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(deps): backfill library traces for ADR-014 cluster

Browse Source 
Approved traces for @sentry/nextjs, @sentry/opentelemetry,
@sentry/node, and @sentry/react — all at ^10.51.0 in
packages/core-shared. Without these files the pre-commit
library-trace hook would fire retroactively on any future
package.json touch; backfill establishes the baseline.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Danijel Martinek
2026-05-14 09:53:04 +00:00
parent 9e7723f9a5
commit cf3f160148
4 changed files with 346 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
docs/library-decisions/2026-05-14-@sentry/nextjs.md Normal file
View File

@@ -0,0 +1,87 @@
---
package: "@sentry/nextjs"
version: "^10.51.0"
tier: core
decision: approved
date: 2026-05-14
deciders: [Danijel Martinek]
adr: adr-014
filter-results:
license: MIT
types: native
maintenance: active
boundary-fit: pass
shadow-check: pass
eu-residency: ok
cve-scan: clean
named-consumer: pass
verification-commands:
- npm view @sentry/nextjs license
- npm view @sentry/nextjs version
- pnpm audit --audit-level=moderate
accepted-cves: []
---
## Filter: license
<!-- Result: MIT -->
`npm view @sentry/nextjs license` returns `MIT`. MIT is on the allowlist.
## Filter: types
<!-- Result: native -->
`@sentry/nextjs` 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 Sentry Inc. The 10.x line sees regular releases tracking Next.js releases. Used by thousands of production Next.js apps; issue tracker shows prompt engagement.
## Filter: boundary-fit
<!-- Result: pass -->
ADR-014 designates Sentry as the error-capture and tracing backend. The ESLint `no-restricted-imports` rule (ADR-014 §6) allowlists `@sentry/*` only within `core-shared/instrumentation/sentry/**`, the apps' `instrumentation*.{ts,mjs}` / `next.config.{mjs}` entry points, and the `core-testing/setup/no-sentry.ts` mock. Feature packages MUST NOT import `@sentry/*` directly — they consume only the vendor-neutral `ITracer`/`ILogger` interfaces.
## Filter: shadow-check
<!-- Result: pass -->
`@sentry/nextjs` is the sole Next.js error-monitoring SDK in the workspace. No competing APM or crash-reporter library (Datadog, New Relic, Rollbar, Bugsnag) is present or proposed.
## Filter: eu-residency
<!-- Result: ok -->
Sentry offers EU-region data residency (hosted at `de.sentry.io`). The workspace's `WEB_NEXT_SENTRY_DSN` can point to an EU-hosted project; the SDK routes all payloads to the DSN host. PII scrubbing at the OTel processor layer (ADR-017, ADR-014 §4) ensures only scrubbed data leaves the process.
## Filter: cve-scan
<!-- Result: clean -->
`pnpm audit --audit-level=moderate` reports no advisories against `@sentry/nextjs` at the time of this trace.
## Filter: named-consumer
<!-- Result: pass -->
`packages/core-shared/src/instrumentation/sentry/` holds the Sentry adapter pair (`SentryTracer`, `SentryLogger`). `apps/web-next/instrumentation.ts` and `apps/web-next/next.config.mjs` are the concrete Next.js-side consumers. Both are named, non-hypothetical consumers.
## Prompt: replaces
No prior error monitoring or distributed tracing library was in place. `@sentry/nextjs` replaces ad-hoc `console.error` logging that provided no stack context, no distributed trace correlation, and no session replay for diagnosing reproduction steps.
## Prompt: migration-cost-out
Moderate. The interface boundary (ADR-014 §1) limits feature-package blast radius to zero — feature code never imports `@sentry/nextjs`. Removal would require swapping the `SentryTracer`/`SentryLogger` adapter pair in `core-shared/instrumentation/sentry/` for a new adapter, updating `apps/web-next/instrumentation.ts` and `next.config.mjs`, and dropping the `WEB_NEXT_SENTRY_DSN` env var. The scope is bounded and mechanical.
## Prompt: alternatives-considered
1. **Datadog APM** — Stronger distributed tracing primitives, but higher cost, heavier SDK footprint, and no built-in session replay. Evaluated and deferred.
2. **New Relic** — Enterprise-grade but requires a New Relic account and agent; no native Next.js SDK at the time of evaluation.
3. **Direct OpenTelemetry export** — Deferred to ADR-017 for the OTel migration layer; Sentry remains the exporter via `@sentry/opentelemetry` bridge.
See ADR-014 for the full decision rationale.

86
docs/library-decisions/2026-05-14-@sentry/node.md Normal file
View File

@@ -0,0 +1,86 @@
---
package: "@sentry/node"
version: "^10.51.0"
tier: core
decision: approved
date: 2026-05-14
deciders: [Danijel Martinek]
adr: adr-014
filter-results:
license: MIT
types: native
maintenance: active
boundary-fit: pass
shadow-check: pass
eu-residency: ok
cve-scan: clean
named-consumer: pass
verification-commands:
- npm view @sentry/node license
- npm view @sentry/node version
- pnpm audit --audit-level=moderate
accepted-cves: []
---
## Filter: license
<!-- Result: MIT -->
`npm view @sentry/node license` returns `MIT`. MIT is on the allowlist.
## Filter: types
<!-- Result: native -->
`@sentry/node` 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 Sentry Inc. The 10.x line is the current major. Regular releases track Node.js LTS versions and fix security issues promptly.
## Filter: boundary-fit
<!-- Result: pass -->
ADR-014 designates Sentry as the error-capture and tracing backend for Node.js server processes. `@sentry/node` is an optional peer dependency of `core-shared` — it is consumed exclusively within `core-shared/instrumentation/sentry/init-server-node.ts` and the CMS app's `instrumentation.ts`. Feature packages MUST NOT import `@sentry/node` directly (ESLint `no-restricted-imports`, ADR-014 §6).
## Filter: shadow-check
<!-- Result: pass -->
`@sentry/node` is the sole Node.js server error-monitoring SDK in the workspace. No competing APM agent or crash reporter is present.
## Filter: eu-residency
<!-- Result: ok -->
Sentry offers EU-region data residency (`de.sentry.io`). The `CMS_SENTRY_DSN` environment variable can point to an EU-hosted project; all payloads route to the DSN host. PII scrubbing at the OTel processor layer (ADR-017, ADR-014 §4) ensures only scrubbed data is exported.
## Filter: cve-scan
<!-- Result: clean -->
`pnpm audit --audit-level=moderate` reports no advisories against `@sentry/node` at the time of this trace.
## Filter: named-consumer
<!-- Result: pass -->
`packages/core-shared` lists `@sentry/node` as an optional peer dependency. `apps/cms/src/instrumentation.ts` is the concrete consumer, initializing the Node SDK for the Payload CMS process. A named, non-hypothetical consumer exists today.
## Prompt: replaces
No prior server-side error monitoring was in place for the CMS process. `@sentry/node` replaces unstructured `console.error` calls that left CMS mutation failures undetected in production.
## Prompt: migration-cost-out
Low. `@sentry/node` is used only in `core-shared/instrumentation/sentry/init-server-node.ts` and the CMS app's `instrumentation.ts`. The interface boundary (ADR-014 §1) means no feature package references it. Replacement requires swapping the initialization file and updating the `CMS_SENTRY_DSN` env var.
## Prompt: alternatives-considered
1. **`@sentry/nextjs` for CMS** — Rejected: the Payload CMS process is a plain Node server, not a Next.js app. `@sentry/node` is the correct SDK for non-Next processes.
2. **OpenTelemetry OTLP exporter only** — Considered but deferred; Sentry's session grouping and alert routing add value beyond raw OTLP. The bridge via `@sentry/opentelemetry` preserves OTel portability.
See ADR-014 for the full decision rationale.

86
docs/library-decisions/2026-05-14-@sentry/opentelemetry.md Normal file
View File

@@ -0,0 +1,86 @@
---
package: "@sentry/opentelemetry"
version: "^10.51.0"
tier: core
decision: approved
date: 2026-05-14
deciders: [Danijel Martinek]
adr: adr-014
filter-results:
license: MIT
types: native
maintenance: active
boundary-fit: pass
shadow-check: pass
eu-residency: ok
cve-scan: clean
named-consumer: pass
verification-commands:
- npm view @sentry/opentelemetry license
- npm view @sentry/opentelemetry version
- pnpm audit --audit-level=moderate
accepted-cves: []
---
## Filter: license
<!-- Result: MIT -->
`npm view @sentry/opentelemetry license` returns `MIT`. MIT is on the allowlist.
## Filter: types
<!-- Result: native -->
`@sentry/opentelemetry` 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 Sentry Inc. as the official bridge between the Sentry SDK and the OpenTelemetry SDK. Versions track the `@sentry/*` SDK family; the 10.x line is current.
## Filter: boundary-fit
<!-- Result: pass -->
ADR-014 designates Sentry as the error-capture backend, and ADR-017 mandates OpenTelemetry as the instrumentation substrate. `@sentry/opentelemetry` is the bridge that wires Sentry as an OTel exporter — it belongs exclusively in `core-shared/instrumentation/sentry/` alongside the adapter pair. Feature packages MUST NOT import it directly (ESLint `no-restricted-imports`, ADR-014 §6).
## Filter: shadow-check
<!-- Result: pass -->
`@sentry/opentelemetry` is the only OTel-to-Sentry bridge in the workspace. No competing exporter bridge (e.g., manual `@opentelemetry/exporter-*` wired to Sentry) is present.
## Filter: eu-residency
<!-- Result: ok -->
`@sentry/opentelemetry` is a pure instrumentation adapter with no independent data transmission. All spans and log records it emits are forwarded through the Sentry SDK, which routes to the DSN host (EU-hosted if configured). EU residency is governed by the DSN setting, not this package.
## Filter: cve-scan
<!-- Result: clean -->
`pnpm audit --audit-level=moderate` reports no advisories against `@sentry/opentelemetry` at the time of this trace.
## Filter: named-consumer
<!-- Result: pass -->
`packages/core-shared/src/instrumentation/sentry/` is the sole consumer. It registers `@sentry/opentelemetry`'s `SentrySpanProcessor` and `SentryPropagator` during OTel SDK initialization so that all OTel spans are also captured as Sentry transactions.
## Prompt: replaces
Prior to ADR-017, the workspace had no OTel substrate. `@sentry/opentelemetry` replaces the need to configure two independent pipelines (a direct Sentry SDK pipeline and a raw OTel SDK pipeline) by letting a single OTel pipeline export to Sentry via the bridge.
## Prompt: migration-cost-out
Low. `@sentry/opentelemetry` is used in one file in `core-shared/instrumentation/sentry/`. Replacing Sentry as the exporter means swapping this bridge for a different `SpanExporter` in that single file. The OTel substrate (ADR-017) remains untouched.
## Prompt: alternatives-considered
1. **Direct Sentry SDK without OTel bridge** — Rejected in ADR-017: coupling feature packages to `@sentry/*` APIs directly would violate vendor isolation. The OTel-first approach keeps instrumentation portable.
2. **`@opentelemetry/exporter-zipkin` / Jaeger** — Open-source trace backends considered but lack Sentry's session replay, error deduplication, and release tracking. Sentry via bridge offers a superset.
See ADR-014 and ADR-017 for the full decision rationale.

87
docs/library-decisions/2026-05-14-@sentry/react.md Normal file
View File

@@ -0,0 +1,87 @@
---
package: "@sentry/react"
version: "^10.51.0"
tier: core
decision: approved
date: 2026-05-14
deciders: [Danijel Martinek]
adr: adr-014
filter-results:
license: MIT
types: native
maintenance: active
boundary-fit: pass
shadow-check: pass
eu-residency: ok
cve-scan: clean
named-consumer: pass
verification-commands:
- npm view @sentry/react license
- npm view @sentry/react version
- pnpm audit --audit-level=moderate
accepted-cves: []
---
## Filter: license
<!-- Result: MIT -->
`npm view @sentry/react license` returns `MIT`. MIT is on the allowlist.
## Filter: types
<!-- Result: native -->
`@sentry/react` 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 Sentry Inc. The 10.x line is current. Regular releases track React minor versions and address browser compatibility issues.
## Filter: boundary-fit
<!-- Result: pass -->
ADR-014 designates Sentry as the error-capture and session-replay backend for browser clients. `@sentry/react` is consumed exclusively in `core-shared/instrumentation/sentry/init-client-react.ts` and the web apps' client-side `instrumentation-client.ts` entry points. Feature packages MUST NOT import `@sentry/react` directly (ESLint `no-restricted-imports`, ADR-014 §6).
## Filter: shadow-check
<!-- Result: pass -->
`@sentry/react` is the sole React browser error-monitoring SDK in the workspace. No competing session-replay or crash-reporter library is present.
## Filter: eu-residency
<!-- Result: ok -->
Sentry offers EU-region data residency (`de.sentry.io`). The `NEXT_PUBLIC_WEB_NEXT_SENTRY_DSN` environment variable can point to an EU-hosted project. Session replay default-masks all text/inputs/media (allowlist empty by default, ADR-014 §4 R34) and `setUser` accepts only `{ id }`, minimising PII exposure at source.
## Filter: cve-scan
<!-- Result: clean -->
`pnpm audit --audit-level=moderate` reports no advisories against `@sentry/react` at the time of this trace.
## Filter: named-consumer
<!-- Result: pass -->
`packages/core-shared` lists `@sentry/react` as an optional peer dependency. `apps/web-next/src/instrumentation-client.ts` is the concrete consumer, initializing the React SDK with session replay for the Next.js browser bundle. A named, non-hypothetical consumer exists today.
## Prompt: replaces
No prior browser error monitoring or session replay was in place. `@sentry/react` replaces unstructured `window.onerror` / uncaught promise rejections that surfaced only in browser dev-tools — invisible to the engineering team in production.
## Prompt: migration-cost-out
Low. `@sentry/react` is initialized in one file per app (`instrumentation-client.ts`). The vendor-neutral `ITracer`/`ILogger` interfaces (ADR-014 §1) ensure feature packages have zero references to it. Removal means replacing the client initialization file and dropping the browser DSN env var.
## Prompt: alternatives-considered
1. **`@sentry/nextjs` on the client** — `@sentry/nextjs` wraps `@sentry/react` for Next.js server-side use. For browser-only client initialization, `@sentry/react` is the more targeted SDK with a smaller bundle size.
2. **LogRocket / FullStory for replay** — Separate replay vendors would add a second SDK with its own PII risk surface. Sentry's built-in replay with default-masking satisfies the requirement with one SDK.
3. **No session replay** — Insufficient for diagnosing hard-to-reproduce user-facing bugs. Replay is opt-in per error event (deferred load), so the cost is bounded to errored sessions.
See ADR-014 for the full decision rationale.