@drawbridge/drawbridge-telemetry

Shared observability helpers for the drawbridge-* monorepo. Provides Sentry scope correlation across HTTP, BullMQ workers, and MongoDB change streams. Pino logger + event emitter arrive in Stage 2; OpenTelemetry SDK in Stage 4.

Install

npm install --save-exact @drawbridge/drawbridge-telemetry

Requires @sentry/core >= 10 as a peer dependency. Backend services satisfy this via @sentry/node; Next.js apps via @sentry/nextjs.

Subpaths

| Subpath | Purpose | | --- | --- | | @drawbridge/drawbridge-telemetry | Core: attachProcessHandlers, withTraceScope, currentTraceId | | @drawbridge/drawbridge-telemetry/express | expressContextMiddleware for Express apps | | @drawbridge/drawbridge-telemetry/bullmq | wrapWorkerHandler, enqueueFromWorker, attachQueueEventsLogger | | @drawbridge/drawbridge-telemetry/stream | enqueueWithTrace for MongoDB change-stream handlers |

Naming conventions

• Event names — <noun>.<verb> past tense, lowercase, dot-separated. Verbs match drawbridge-api's action status vocabulary (processing / succeeded / failed; never pending / completed). Nouns are singular and match Mongo collection names.
• Tag keys — camelCase. Canonical traceId everywhere; X-Request-Id header stays for wire compat.
• Event envelope — { name, traceId, userId, organizationId, data: {...}, createdAt }.
• Reserved keys in job.data — __traceId (double-underscore prefix marks it as infrastructure data, not domain data).

Error context

createLogger().error( error, data ) sends data to Sentry as well as to stdout. Domain meta becomes tags when it is a short scalar (indexed, so you can filter and group on it) and extra otherwise:

logger.error( error, { cycleId : '2026-08-18', step : 'recommend' } );
// Sentry issue carries tags: { cycleId: '2026-08-18', step: 'recommend' }

Keys Sentry owns — user, level, extra, contexts, tags, fingerprint, propagationContext, and the EventHint keys — pass through untouched, and an explicit tags.step beats an inferred one. A call that passes only Sentry's own keys behaves exactly as it always did.

Before 0.0.18 this silently dropped everything: Sentry reads the second argument as an EventHint unless it carries one of its own scope keys, so { step : 'recommend' } was discarded without a warning, on every service. If you are debugging an issue captured by an older build, the meta only ever reached stdout — correlate the Sentry logs stream by timestamp instead.

TraceId flow

HTTP request                  Mongo change event
     │                              │
     ▼ req.id (randomUUID)          ▼ _id._data (resume token)
expressContextMiddleware       enqueueWithTrace
     │                              │
     │ scope.setTag('traceId',_)    │ job.data.__traceId
     ▼                              ▼
Sentry events for request     BullMQ worker
                                    │ wrapWorkerHandler reads
                                    │ job.data.__traceId
                                    ▼
                              scope.setTag('traceId',_)
                                    │
                                    ▼
                              Downstream enqueues
                              via enqueueFromWorker
                              forward active scope's traceId

For cron-style repeatable BullMQ jobs (no parent request or change event), synthesize a __traceId at enqueue time — pass it via data.__traceId to enqueueFromWorker.

Build & publish

npm run build    # tsup + npm publish

Bump version in package.json before publishing.