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

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.