[victor-carv]

Summary

The first version of @codelittinc/otel-node: one in-process OpenTelemetry SDK for every Carbon Node app. It is extracted from Backbone's packages/telemetry, so Backbone's tested behaviour is the starting point; its app-specific constants became options. Part of codelittinc/carbon-backbone#825 (Phase 6, the shared package).

• SDK boot: traces, metrics, OTLP logs and Pyroscope profiles, exported only when OTEL_EXPORTER_OTLP_ENDPOINT is set. With no endpoint, no SDK module loads. startTelemetry never throws or rejects, and shutdownTelemetry is bounded.
• Layer 1 of the two-layer PII scrub: span names and attributes, log bodies and fields, and metric labels are scrubbed before any exporter sees them. The scrub contract (src/scrub-contract.json) now lives here; the agent's layer 2 in carbon-observability follows it.
• Logging: a pino logger whose scrubbed lines go to OTLP logs. A new captureConsole() sends console.warn and console.error through the same scrub, so an app that logs with console needs no rewrite. Console capture never exports anything log would not.
• Entries:
  • . is the main API.
  • ./register is for node --import with no options.
  • ./bullmq holds the BullMQ telemetry. bullmq ^6.3.8 is the only optional peer.
  • ./url-credentials is browser-safe: no Node and no OTel imports.
  • ./testing holds the test helpers.
• Options:
  • serviceName
  • logScope
  • metricViews (instrument prefix plus an allowed-label list)
  • instrumentations: app-supplied, so Prisma matches the app's version
  • redactKeys: adds keys to the default list and never removes one. It also applies to span attribute keys: a whole name anywhere, or a last segment unless the attribute is one of 54 listed attributes the package's instrumentations emit (such as http.route or db.system.name). Anything unlisted fails closed
  • onError
  • ignoredPaths
• Install by commit: dist/ is committed and marked as generated. CI fails when it differs from a fresh build. There is no license, by decision: the repo is public only so apps can install it without a token.

Changes from Backbone at 6a948f21 that its move (next PR) will declare

• The tracer scope name is now @codelittinc/otel-node, and Prisma instrumentation registers after pg.
• PostHog stays in Backbone. Backbone's wrapper flushes it on shutdown and passes logScope: "backbone".
• log now scrubs values it used to leak: functions, and Maps, Sets, RegExps or Date subclasses with their own toJSON.
• Error messages that are not strings, and Prisma meta.target items, are scrubbed too.
• Format placeholders render a few rare values differently (for example, %d with a Date).
• A nested typed array that is not a Buffer exports { bytes }.

Ordinary values log byte for byte as before.

Testing

• pnpm typecheck passes.
• pnpm test: 38 files, 947 tests, all passing. Moved Backbone tests keep their assertions, with Backbone's values passed as options. Two assertion lines changed: one now imports from ./bullmq, and the lockstep check now covers this package's own manifest. The new tests cover:
  • a run with no endpoint
  • an unreachable endpoint, which delays a request by at most 50 ms
  • console capture
  • scope filtering
  • metric views
  • the ./url-credentials import graph
  • typechecking the ./bullmq types without bullmq installed
  • a table of 14 serialization hooks × 6 positions, through both log and console capture
• pnpm build matches the committed dist/.
• An install by commit from a local git+file: clone works with no build step: every entry imports, and register boots the SDK.
• Reviews:
  • a task review with two fix rounds
  • a whole-branch review with one fix wave and a scoped re-review
  • no open Critical or Important findings

Not yet verified: the token-free github: install, which needs this branch on GitHub, and Backbone's own suite against the package, which is the next PR.

🤖 Generated with Claude Code

[victor-carv]

QA Check Report — codelittinc/otel-node feat/otel-node-package (000e84b..f56b7d1)

Risk level: HIGH

Base HIGH: 85 files and 7,526 lines, excluding dist/ and the lockfile. Escalations: none.

• A written plan exists (Backbone tasks/observability-platform/phase-6-otel-node.md, with rulings R184–R212).
• Every file is new to this repo, so none counts as unhealthy.

Spec discipline

• Spec or acceptance criteria: yes.
  • The plan's Phase 6 Task 16, amended by controller rulings in the session ledger.
  • The diff matches it.
  • Deviations are recorded as rulings: the API superset, the ./bullmq subpath, no next peer, and keeping the event name telemetry_start_failed.

Complexity (Quality Paradox)

• Files touched: 85 (36 src, 38 test files, config, CI, README).
  • Most moved byte-identical from Backbone packages/telemetry at 6a948f21. The moved-file diff against the originals is 772 lines.
  • New logic: console-capture.ts, options.ts, register.ts, app-keys.ts, plus scrub hardening in log-redact.ts and log-errors.ts.
• Rework signals:
  • console-capture.ts, log-redact.ts, sdk.ts and app-keys.ts were each re-touched in 2–5 review fix rounds within this PR. That is in-PR convergence on review findings, not post-merge rework.
  • Each round added a test that failed first.
  • app-keys.ts went through two designs: a namespace exemption, then the exact list of attribute names.
• Unhealthy files: none. The largest file is 287 lines (a test); all are ≤ 300.
• Sustainable velocity concern: no. Every new code path has tests: 38 files, 947 tests.

Test integrity

• No test deleted, skipped or .only'd.
• Of the moved Backbone tests, two lost an original assertion line, both justified:
  • sdk-lazy.test.ts: the same assertion, now importing bullmqTelemetry from the ./bullmq subpath (R198).
  • otel-lockstep.test.ts: the cross-workspace drift check became a per-family single-version check over this package's own manifest (R187). Backbone keeps its workspace version.
• Replaced within this PR: round 3's "bad redact key fails the start" test became "a bad key is dropped with a type-only warning; valid keys apply". This follows ruling R209 and replaces a test added earlier in the same PR, not a pre-existing one.
• New tests assert observable output (exported OTLP records, stdout lines, span attributes), not mocks:
  • serialization-hooks.test.ts: 14 hooks × 6 positions, through both log and console capture. It also asserts log_redaction_failed is absent, so a fail-closed sanitizer can't pass it.

Dependency provenance

• Dependency files changed. Run /supply-chain-check before merging. package.json and pnpm-lock.yaml are new in this repo.
• All 22 runtime dependencies and the bullmq dev dependency are pinned exactly as Backbone pins them at 6a948f21. Their provenance is unchanged.
• New dev-only dependencies:
  • vitest@3.2.7: exists, package created 2021, a well-known maintainer org.
  • @types/node@22.19.17: exists, the DefinitelyTyped scope.
  • typescript moved from a range to the exact 5.9.3.
• No name proximity concerns. Peers: bullmq ^6.3.8, optional (matches bullmq-otel@2.0.1).

Validation gaps (Quality Paradox)

• startTelemetry deliberately never throws or rejects:

  • Failures log telemetry_start_failed.
  • Bad redact keys log invalid_redact_key, carrying the entry's type only.
  • A restart with different options logs telemetry_restart_ignored.

  This is intended and declared: telemetry must not take down the app. It is tested.

• Not verified in this PR:

  • the token-free github: install, which needs the branch on GitHub (verify after push)
  • Backbone's own suite against the package (P6-T17)
  • CI on GitHub (first run after push)

AI-specific concerns (Quality Paradox)

• Hallucinated APIs: none found.
  • CI action SHAs were checked against their tags (checkout v7.0.1, action-setup v6.1.0, setup-node v7.1.0).
  • The @prisma/instrumentation 7.10.0 attribute list was checked against the published tarballs.
• Duplicated logic: url-credentials.ts has one copy here. Backbone's web copy is removed in P6-T17 (R184).
• Silent failures: catch blocks in console-capture (the console line is already written) and in shutdown are intentional and commented. No 200-on-failure paths.
• Slop: none significant. Comments state end results; no dates or internal ids.

Contract compliance

• The public API is typed. The README lists every export and type.
• The scrub contract src/scrub-contract.json is pinned by scrub-contract.test.ts. Its update hint names carbon-observability as the follower; that platform PR (P6-T16c) is pending (R191).

Architecture violations

• None blocking.
• Process-global state (started config, applied options, app keys) is module-level by design: one SDK per process. Each piece has a test seam.
• Adapter boundary: OTel and pino sit behind the package's own API, and apps import only @codelittinc/otel-node.

Recommended actions

1. After push: confirm CI is green and that a github:codelittinc/otel-node#<sha> install works with no token.
2. Run /supply-chain-check on the new lockfile.
3. Land the platform contract PR (P6-T16c) before P6-T17 deletes Backbone's copy.