@drawbridge/drawbridge-telemetry 0.0.1

package/README.md

@@ -0,0 +1,61 @@
+# @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
+
+```sh
+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
+
+Codified in the plan at `~/.claude/plans/yes-lets-see-it-enumerated-bumblebee.md`. Summary:
+
+- **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
+
+```sh
+npm run build
+```
+
+Builds CJS + ESM bundles into `dist/` and publishes. Bump `version` in package.json before publishing.

package/dist/bullmq.cjs

@@ -0,0 +1,108 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// bullmq.js
+var bullmq_exports = {};
+__export(bullmq_exports, {
+  attachQueueEventsLogger: () => attachQueueEventsLogger,
+  enqueueFromWorker: () => enqueueFromWorker,
+  wrapWorkerHandler: () => wrapWorkerHandler
+});
+module.exports = __toCommonJS(bullmq_exports);
+var Sentry2 = __toESM(require("@sentry/core"), 1);
+
+// index.js
+var Sentry = __toESM(require("@sentry/core"), 1);
+var withTraceScope = (traceId, fn) => Sentry.withScope((scope) => {
+  if (traceId) scope.setTag("traceId", traceId);
+  return fn(scope);
+});
+var currentTraceId = () => {
+  var _a, _b;
+  const scope = Sentry.getCurrentScope();
+  const data = (_a = scope == null ? void 0 : scope.getScopeData) == null ? void 0 : _a.call(scope);
+  return (_b = data == null ? void 0 : data.tags) == null ? void 0 : _b.traceId;
+};
+
+// bullmq.js
+var wrapWorkerHandler = (handler) => async (jobData, job) => {
+  var _a;
+  const traceId = (_a = job == null ? void 0 : job.data) == null ? void 0 : _a.__traceId;
+  return withTraceScope(traceId, (scope) => {
+    if (job == null ? void 0 : job.queueName) {
+      scope.setTag("queue", job.queueName);
+    }
+    ;
+    if (job == null ? void 0 : job.name) {
+      scope.setTag("jobName", job.name);
+    }
+    ;
+    return handler(jobData, job);
+  });
+};
+var enqueueFromWorker = async (queue, name, data, options = {}) => {
+  const traceId = currentTraceId();
+  return queue.add(
+    name,
+    {
+      ...data,
+      __traceId: (data == null ? void 0 : data.__traceId) || traceId
+    },
+    options
+  );
+};
+var attachQueueEventsLogger = (queueEvents, queueName, logger) => {
+  if (!(logger == null ? void 0 : logger.event)) return;
+  queueEvents.on("completed", ({ jobId, returnvalue, prev }) => {
+    logger.event("job.completed", {
+      jobId,
+      queue: queueName,
+      prev
+    });
+  });
+  queueEvents.on("failed", ({ jobId, failedReason, prev }) => {
+    logger.event("job.failed", {
+      jobId,
+      queue: queueName,
+      failedReason,
+      prev
+    });
+  });
+  queueEvents.on("stalled", ({ jobId }) => {
+    logger.event("job.stalled", {
+      jobId,
+      queue: queueName
+    });
+  });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  attachQueueEventsLogger,
+  enqueueFromWorker,
+  wrapWorkerHandler
+});

package/dist/bullmq.d.cts

@@ -0,0 +1,101 @@
+import { currentTraceId, withTraceScope } from './index.cjs';
+import '@sentry/core';
+
+// Wrap a BullMQ worker handler so it runs inside a Sentry scope tagged
+// with the job's traceId, queue name, and job name. The wrapped handler
+// keeps the same `( jobData, job )` signature the existing queue-factory
+// uses, so worker code itself doesn't change.
+//
+// The traceId originates from one of two places:
+//   - HTTP request: the API's req.id is forwarded as job.data.__traceId
+//   - Change stream: the Mongo resume token (_id._data) is forwarded
+// Either way, the wrapper just reads job.data.__traceId.
+
+const wrapWorkerHandler = ( handler ) => async ( jobData, job ) => {
+
+	const traceId = job?.data?.__traceId;
+
+	return withTraceScope( traceId, ( scope ) => {
+
+		if( job?.queueName ){
+
+			scope.setTag( 'queue', job.queueName );
+
+		}
+		if( job?.name ){
+
+			scope.setTag( 'jobName', job.name );
+
+		}
+		return handler( jobData, job );
+
+	} );
+
+};
+
+// Enqueue a downstream BullMQ job from inside a worker handler, forwarding
+// the active scope's traceId as job.data.__traceId. Use this in place of
+// `queue.add( ... )` inside any handler that creates more work.
+//
+// If no traceId is on the active scope (e.g. enqueuing outside any scope),
+// the new job inherits no trace — downstream events won't correlate. This
+// is the expected fallback for cron-style jobs; pass an explicit __traceId
+// in `data` if you want to override the active scope's value.
+
+const enqueueFromWorker = async ( queue, name, data, options = {} ) => {
+
+	const traceId = currentTraceId();
+
+	return queue.add(
+		name,
+		{
+			...data,
+			__traceId : data?.__traceId || traceId
+		},
+		options
+	);
+
+};
+
+// Attach a QueueEvents listener that emits structured `job.completed` and
+// `job.failed` records to the active Sentry logger. Use one per queue.
+// Stage 2 only — Stage 1 ships the helper but it's a no-op until the
+// unified logger lands.
+
+const attachQueueEventsLogger = ( queueEvents, queueName, logger ) => {
+
+	if( ! logger?.event ) return;
+
+	queueEvents.on( 'completed', ({ jobId, returnvalue, prev }) => {
+
+		logger.event( 'job.completed', {
+			jobId,
+			queue : queueName,
+			prev
+		});
+
+	});
+
+	queueEvents.on( 'failed', ({ jobId, failedReason, prev }) => {
+
+		logger.event( 'job.failed', {
+			jobId,
+			queue : queueName,
+			failedReason,
+			prev
+		});
+
+	});
+
+	queueEvents.on( 'stalled', ({ jobId }) => {
+
+		logger.event( 'job.stalled', {
+			jobId,
+			queue : queueName
+		});
+
+	});
+
+};
+
+export { attachQueueEventsLogger, enqueueFromWorker, wrapWorkerHandler };

package/dist/bullmq.d.ts

@@ -0,0 +1,101 @@
+import { currentTraceId, withTraceScope } from './index.js';
+import '@sentry/core';
+
+// Wrap a BullMQ worker handler so it runs inside a Sentry scope tagged
+// with the job's traceId, queue name, and job name. The wrapped handler
+// keeps the same `( jobData, job )` signature the existing queue-factory
+// uses, so worker code itself doesn't change.
+//
+// The traceId originates from one of two places:
+//   - HTTP request: the API's req.id is forwarded as job.data.__traceId
+//   - Change stream: the Mongo resume token (_id._data) is forwarded
+// Either way, the wrapper just reads job.data.__traceId.
+
+const wrapWorkerHandler = ( handler ) => async ( jobData, job ) => {
+
+	const traceId = job?.data?.__traceId;
+
+	return withTraceScope( traceId, ( scope ) => {
+
+		if( job?.queueName ){
+
+			scope.setTag( 'queue', job.queueName );
+
+		}
+		if( job?.name ){
+
+			scope.setTag( 'jobName', job.name );
+
+		}
+		return handler( jobData, job );
+
+	} );
+
+};
+
+// Enqueue a downstream BullMQ job from inside a worker handler, forwarding
+// the active scope's traceId as job.data.__traceId. Use this in place of
+// `queue.add( ... )` inside any handler that creates more work.
+//
+// If no traceId is on the active scope (e.g. enqueuing outside any scope),
+// the new job inherits no trace — downstream events won't correlate. This
+// is the expected fallback for cron-style jobs; pass an explicit __traceId
+// in `data` if you want to override the active scope's value.
+
+const enqueueFromWorker = async ( queue, name, data, options = {} ) => {
+
+	const traceId = currentTraceId();
+
+	return queue.add(
+		name,
+		{
+			...data,
+			__traceId : data?.__traceId || traceId
+		},
+		options
+	);
+
+};
+
+// Attach a QueueEvents listener that emits structured `job.completed` and
+// `job.failed` records to the active Sentry logger. Use one per queue.
+// Stage 2 only — Stage 1 ships the helper but it's a no-op until the
+// unified logger lands.
+
+const attachQueueEventsLogger = ( queueEvents, queueName, logger ) => {
+
+	if( ! logger?.event ) return;
+
+	queueEvents.on( 'completed', ({ jobId, returnvalue, prev }) => {
+
+		logger.event( 'job.completed', {
+			jobId,
+			queue : queueName,
+			prev
+		});
+
+	});
+
+	queueEvents.on( 'failed', ({ jobId, failedReason, prev }) => {
+
+		logger.event( 'job.failed', {
+			jobId,
+			queue : queueName,
+			failedReason,
+			prev
+		});
+
+	});
+
+	queueEvents.on( 'stalled', ({ jobId }) => {
+
+		logger.event( 'job.stalled', {
+			jobId,
+			queue : queueName
+		});
+
+	});
+
+};
+
+export { attachQueueEventsLogger, enqueueFromWorker, wrapWorkerHandler };

package/dist/bullmq.js

@@ -0,0 +1,62 @@
+import {
+  currentTraceId,
+  withTraceScope
+} from "./chunk-SRV5HFQT.js";
+
+// bullmq.js
+import * as Sentry from "@sentry/core";
+var wrapWorkerHandler = (handler) => async (jobData, job) => {
+  var _a;
+  const traceId = (_a = job == null ? void 0 : job.data) == null ? void 0 : _a.__traceId;
+  return withTraceScope(traceId, (scope) => {
+    if (job == null ? void 0 : job.queueName) {
+      scope.setTag("queue", job.queueName);
+    }
+    ;
+    if (job == null ? void 0 : job.name) {
+      scope.setTag("jobName", job.name);
+    }
+    ;
+    return handler(jobData, job);
+  });
+};
+var enqueueFromWorker = async (queue, name, data, options = {}) => {
+  const traceId = currentTraceId();
+  return queue.add(
+    name,
+    {
+      ...data,
+      __traceId: (data == null ? void 0 : data.__traceId) || traceId
+    },
+    options
+  );
+};
+var attachQueueEventsLogger = (queueEvents, queueName, logger) => {
+  if (!(logger == null ? void 0 : logger.event)) return;
+  queueEvents.on("completed", ({ jobId, returnvalue, prev }) => {
+    logger.event("job.completed", {
+      jobId,
+      queue: queueName,
+      prev
+    });
+  });
+  queueEvents.on("failed", ({ jobId, failedReason, prev }) => {
+    logger.event("job.failed", {
+      jobId,
+      queue: queueName,
+      failedReason,
+      prev
+    });
+  });
+  queueEvents.on("stalled", ({ jobId }) => {
+    logger.event("job.stalled", {
+      jobId,
+      queue: queueName
+    });
+  });
+};
+export {
+  attachQueueEventsLogger,
+  enqueueFromWorker,
+  wrapWorkerHandler
+};

package/dist/chunk-SRV5HFQT.js

@@ -0,0 +1,50 @@
+// index.js
+import * as Sentry from "@sentry/core";
+var attached = false;
+var attachProcessHandlers = () => {
+  if (attached) return;
+  attached = true;
+  process.on("uncaughtException", (error) => {
+    Sentry.captureException(error, {
+      extra: {
+        source: "uncaughtException"
+      }
+    });
+  });
+  process.on("unhandledRejection", (reason) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    Sentry.captureException(error, {
+      extra: {
+        source: "unhandledRejection"
+      }
+    });
+  });
+  process.on("exit", (code) => {
+    console.error("[process exit] code=" + code);
+  });
+  process.on("beforeExit", (code) => {
+    console.error("[process beforeExit] code=" + code + " \u2014 event loop empty");
+  });
+  const signals = ["SIGTERM", "SIGINT", "SIGHUP", "SIGQUIT", "SIGUSR2"];
+  signals.forEach((signal) => {
+    process.on(signal, () => {
+      console.error("[process signal] " + signal + " received");
+    });
+  });
+};
+var withTraceScope = (traceId, fn) => Sentry.withScope((scope) => {
+  if (traceId) scope.setTag("traceId", traceId);
+  return fn(scope);
+});
+var currentTraceId = () => {
+  var _a, _b;
+  const scope = Sentry.getCurrentScope();
+  const data = (_a = scope == null ? void 0 : scope.getScopeData) == null ? void 0 : _a.call(scope);
+  return (_b = data == null ? void 0 : data.tags) == null ? void 0 : _b.traceId;
+};
+
+export {
+  attachProcessHandlers,
+  withTraceScope,
+  currentTraceId
+};

package/dist/express.cjs

@@ -0,0 +1,66 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// express.js
+var express_exports = {};
+__export(express_exports, {
+  expressContextMiddleware: () => expressContextMiddleware
+});
+module.exports = __toCommonJS(express_exports);
+var Sentry = __toESM(require("@sentry/core"), 1);
+var expressContextMiddleware = () => (req, res, next) => {
+  const scope = Sentry.getCurrentScope();
+  if (req == null ? void 0 : req.id) {
+    scope.setTag("traceId", req.id);
+  }
+  ;
+  if (req == null ? void 0 : req.user) {
+    scope.setUser({
+      id: req.user.id || req.user._id,
+      email: req.user.email
+    });
+  }
+  ;
+  if (req == null ? void 0 : req.organization) {
+    scope.setTag("organization", req.organization.id || req.organization._id);
+  }
+  ;
+  if (req == null ? void 0 : req.method) {
+    scope.setTag("method", req.method);
+  }
+  ;
+  if (req == null ? void 0 : req.path) {
+    scope.setTag("route", req.path);
+  }
+  ;
+  next();
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  expressContextMiddleware
+});

package/dist/express.d.cts

@@ -0,0 +1,53 @@
+import * as Sentry from '@sentry/core';
+
+// Express middleware that tags the active Sentry scope with the current
+// user/organization/route/method/traceId. Mount AFTER auth resolution (so
+// req.user and req.organization are populated) and AFTER any req.id
+// middleware (so req.id exists to use as the traceId).
+//
+// Every Sentry event captured during this request — and any downstream
+// BullMQ jobs that propagate the traceId via job.data.__traceId — is
+// filterable by these tags. Without this, errors arrive in Sentry as
+// anonymous stack traces.
+
+const expressContextMiddleware = () => ( req, res, next ) => {
+
+	const scope = Sentry.getCurrentScope();
+
+	if( req?.id ){
+
+		scope.setTag( 'traceId', req.id );
+
+	}
+	if( req?.user ){
+
+		scope.setUser({
+			id : req.user.id || req.user._id,
+			email : req.user.email
+		});
+
+	}
+	if( req?.organization ){
+
+		scope.setTag( 'organization', req.organization.id || req.organization._id );
+
+	}
+	if( req?.method ){
+
+		scope.setTag( 'method', req.method );
+
+	}
+	// req.route is set by Express only AFTER route matching, which hasn't
+	// happened yet at middleware time. Use req.path as a best-effort route
+	// tag — it captures the URL hit; aggregation by route pattern is left
+	// to a future res.on('finish') refinement.
+	if( req?.path ){
+
+		scope.setTag( 'route', req.path );
+
+	}
+	next();
+
+};
+
+export { expressContextMiddleware };

package/dist/express.d.ts

@@ -0,0 +1,53 @@
+import * as Sentry from '@sentry/core';
+
+// Express middleware that tags the active Sentry scope with the current
+// user/organization/route/method/traceId. Mount AFTER auth resolution (so
+// req.user and req.organization are populated) and AFTER any req.id
+// middleware (so req.id exists to use as the traceId).
+//
+// Every Sentry event captured during this request — and any downstream
+// BullMQ jobs that propagate the traceId via job.data.__traceId — is
+// filterable by these tags. Without this, errors arrive in Sentry as
+// anonymous stack traces.
+
+const expressContextMiddleware = () => ( req, res, next ) => {
+
+	const scope = Sentry.getCurrentScope();
+
+	if( req?.id ){
+
+		scope.setTag( 'traceId', req.id );
+
+	}
+	if( req?.user ){
+
+		scope.setUser({
+			id : req.user.id || req.user._id,
+			email : req.user.email
+		});
+
+	}
+	if( req?.organization ){
+
+		scope.setTag( 'organization', req.organization.id || req.organization._id );
+
+	}
+	if( req?.method ){
+
+		scope.setTag( 'method', req.method );
+
+	}
+	// req.route is set by Express only AFTER route matching, which hasn't
+	// happened yet at middleware time. Use req.path as a best-effort route
+	// tag — it captures the URL hit; aggregation by route pattern is left
+	// to a future res.on('finish') refinement.
+	if( req?.path ){
+
+		scope.setTag( 'route', req.path );
+
+	}
+	next();
+
+};
+
+export { expressContextMiddleware };

package/dist/express.js

@@ -0,0 +1,32 @@
+// express.js
+import * as Sentry from "@sentry/core";
+var expressContextMiddleware = () => (req, res, next) => {
+  const scope = Sentry.getCurrentScope();
+  if (req == null ? void 0 : req.id) {
+    scope.setTag("traceId", req.id);
+  }
+  ;
+  if (req == null ? void 0 : req.user) {
+    scope.setUser({
+      id: req.user.id || req.user._id,
+      email: req.user.email
+    });
+  }
+  ;
+  if (req == null ? void 0 : req.organization) {
+    scope.setTag("organization", req.organization.id || req.organization._id);
+  }
+  ;
+  if (req == null ? void 0 : req.method) {
+    scope.setTag("method", req.method);
+  }
+  ;
+  if (req == null ? void 0 : req.path) {
+    scope.setTag("route", req.path);
+  }
+  ;
+  next();
+};
+export {
+  expressContextMiddleware
+};

package/dist/index.cjs

@@ -0,0 +1,85 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.js
+var index_exports = {};
+__export(index_exports, {
+  attachProcessHandlers: () => attachProcessHandlers,
+  currentTraceId: () => currentTraceId,
+  withTraceScope: () => withTraceScope
+});
+module.exports = __toCommonJS(index_exports);
+var Sentry = __toESM(require("@sentry/core"), 1);
+var attached = false;
+var attachProcessHandlers = () => {
+  if (attached) return;
+  attached = true;
+  process.on("uncaughtException", (error) => {
+    Sentry.captureException(error, {
+      extra: {
+        source: "uncaughtException"
+      }
+    });
+  });
+  process.on("unhandledRejection", (reason) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    Sentry.captureException(error, {
+      extra: {
+        source: "unhandledRejection"
+      }
+    });
+  });
+  process.on("exit", (code) => {
+    console.error("[process exit] code=" + code);
+  });
+  process.on("beforeExit", (code) => {
+    console.error("[process beforeExit] code=" + code + " \u2014 event loop empty");
+  });
+  const signals = ["SIGTERM", "SIGINT", "SIGHUP", "SIGQUIT", "SIGUSR2"];
+  signals.forEach((signal) => {
+    process.on(signal, () => {
+      console.error("[process signal] " + signal + " received");
+    });
+  });
+};
+var withTraceScope = (traceId, fn) => Sentry.withScope((scope) => {
+  if (traceId) scope.setTag("traceId", traceId);
+  return fn(scope);
+});
+var currentTraceId = () => {
+  var _a, _b;
+  const scope = Sentry.getCurrentScope();
+  const data = (_a = scope == null ? void 0 : scope.getScopeData) == null ? void 0 : _a.call(scope);
+  return (_b = data == null ? void 0 : data.tags) == null ? void 0 : _b.traceId;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  attachProcessHandlers,
+  currentTraceId,
+  withTraceScope
+});

package/dist/index.d.cts

@@ -0,0 +1,93 @@
+import * as Sentry from '@sentry/core';
+
+// Diagnostic process-level handlers. Surfaces unhandled async errors to
+// Sentry (without these, modern Node defaults silently exit) and logs
+// exit-path signals to stderr so an operator can diagnose crashes.
+// Does NOT trigger shutdown — each service owns its shutdown logic.
+//
+// Idempotent: calling twice is a no-op so accidental double-registration
+// during hot reloads or test setups doesn't stack listeners.
+
+let attached = false;
+
+const attachProcessHandlers = () => {
+
+	if( attached ) return;
+
+	attached = true;
+
+	process.on( 'uncaughtException', ( error ) => {
+
+		Sentry.captureException( error, {
+			extra : {
+				source : 'uncaughtException'
+			}
+		});
+
+	});
+
+	process.on( 'unhandledRejection', ( reason ) => {
+
+		const error = reason instanceof Error ? reason : new Error( String( reason ) );
+
+		Sentry.captureException( error, {
+			extra : {
+				source : 'unhandledRejection'
+			}
+		});
+
+	});
+
+	// Sentry can't flush from here — V8 is tearing down. stderr only.
+	process.on( 'exit', ( code ) => {
+
+		console.error( '[process exit] code=' + code );
+
+	});
+
+	process.on( 'beforeExit', ( code ) => {
+
+		console.error( '[process beforeExit] code=' + code + ' — event loop empty' );
+
+	});
+
+	const signals = [ 'SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT', 'SIGUSR2' ];
+
+	signals.forEach( ( signal ) => {
+
+		process.on( signal, () => {
+
+			console.error( '[process signal] ' + signal + ' received' );
+
+		});
+
+	} );
+
+};
+
+// Run fn inside a Sentry scope with traceId tag set. The callback receives
+// the forked scope so callers can attach additional tags without re-reading
+// the active scope. Returns whatever fn returns (including promises).
+
+const withTraceScope = ( traceId, fn ) => Sentry.withScope( ( scope ) => {
+
+	if( traceId ) scope.setTag( 'traceId', traceId );
+
+	return fn( scope );
+
+} );
+
+// Read the active scope's traceId. Used by helpers that need to forward
+// the current request/job's trace into downstream work (e.g. enqueuing a
+// new BullMQ job from inside a worker handler).
+
+const currentTraceId = () => {
+
+	const scope = Sentry.getCurrentScope();
+	const data = scope?.getScopeData?.();
+
+	return data?.tags?.traceId;
+
+};
+
+export { attachProcessHandlers, currentTraceId, withTraceScope };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import * as Sentry from '@sentry/core';
+
+// Diagnostic process-level handlers. Surfaces unhandled async errors to
+// Sentry (without these, modern Node defaults silently exit) and logs
+// exit-path signals to stderr so an operator can diagnose crashes.
+// Does NOT trigger shutdown — each service owns its shutdown logic.
+//
+// Idempotent: calling twice is a no-op so accidental double-registration
+// during hot reloads or test setups doesn't stack listeners.
+
+let attached = false;
+
+const attachProcessHandlers = () => {
+
+	if( attached ) return;
+
+	attached = true;
+
+	process.on( 'uncaughtException', ( error ) => {
+
+		Sentry.captureException( error, {
+			extra : {
+				source : 'uncaughtException'
+			}
+		});
+
+	});
+
+	process.on( 'unhandledRejection', ( reason ) => {
+
+		const error = reason instanceof Error ? reason : new Error( String( reason ) );
+
+		Sentry.captureException( error, {
+			extra : {
+				source : 'unhandledRejection'
+			}
+		});
+
+	});
+
+	// Sentry can't flush from here — V8 is tearing down. stderr only.
+	process.on( 'exit', ( code ) => {
+
+		console.error( '[process exit] code=' + code );
+
+	});
+
+	process.on( 'beforeExit', ( code ) => {
+
+		console.error( '[process beforeExit] code=' + code + ' — event loop empty' );
+
+	});
+
+	const signals = [ 'SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT', 'SIGUSR2' ];
+
+	signals.forEach( ( signal ) => {
+
+		process.on( signal, () => {
+
+			console.error( '[process signal] ' + signal + ' received' );
+
+		});
+
+	} );
+
+};
+
+// Run fn inside a Sentry scope with traceId tag set. The callback receives
+// the forked scope so callers can attach additional tags without re-reading
+// the active scope. Returns whatever fn returns (including promises).
+
+const withTraceScope = ( traceId, fn ) => Sentry.withScope( ( scope ) => {
+
+	if( traceId ) scope.setTag( 'traceId', traceId );
+
+	return fn( scope );
+
+} );
+
+// Read the active scope's traceId. Used by helpers that need to forward
+// the current request/job's trace into downstream work (e.g. enqueuing a
+// new BullMQ job from inside a worker handler).
+
+const currentTraceId = () => {
+
+	const scope = Sentry.getCurrentScope();
+	const data = scope?.getScopeData?.();
+
+	return data?.tags?.traceId;
+
+};
+
+export { attachProcessHandlers, currentTraceId, withTraceScope };

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  attachProcessHandlers,
+  currentTraceId,
+  withTraceScope
+} from "./chunk-SRV5HFQT.js";
+export {
+  attachProcessHandlers,
+  currentTraceId,
+  withTraceScope
+};

package/dist/stream.cjs

@@ -0,0 +1,39 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// stream.js
+var stream_exports = {};
+__export(stream_exports, {
+  enqueueWithTrace: () => enqueueWithTrace
+});
+module.exports = __toCommonJS(stream_exports);
+var enqueueWithTrace = async (queue, name, data, resumeToken, options = {}) => {
+  const traceId = (resumeToken == null ? void 0 : resumeToken._data) || String(resumeToken);
+  return queue.add(
+    name,
+    {
+      ...data,
+      __traceId: traceId
+    },
+    options
+  );
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  enqueueWithTrace
+});

package/dist/stream.d.cts

@@ -0,0 +1,28 @@
+// Enqueue a BullMQ job from a change-stream handler, forwarding the
+// MongoDB change-event resume token as the __traceId. The resume token
+// (_id._data) is identical for every cursor observing the same oplog
+// event, so all sync replicas compute the same traceId — combined with
+// the BullMQ jobId derived from the same token, this gives both per-event
+// dedup (jobId) AND per-event trace correlation (traceId) from a single
+// source of truth.
+//
+// Callers retain control of the jobId via `options` — the resume-token-as-
+// jobId convention lives in stream.js, not here, because it depends on the
+// caller's choice of collection/operation namespace.
+
+const enqueueWithTrace = async ( queue, name, data, resumeToken, options = {} ) => {
+
+	const traceId = resumeToken?._data || String( resumeToken );
+
+	return queue.add(
+		name,
+		{
+			...data,
+			__traceId : traceId
+		},
+		options
+	);
+
+};
+
+export { enqueueWithTrace };

package/dist/stream.d.ts

@@ -0,0 +1,28 @@
+// Enqueue a BullMQ job from a change-stream handler, forwarding the
+// MongoDB change-event resume token as the __traceId. The resume token
+// (_id._data) is identical for every cursor observing the same oplog
+// event, so all sync replicas compute the same traceId — combined with
+// the BullMQ jobId derived from the same token, this gives both per-event
+// dedup (jobId) AND per-event trace correlation (traceId) from a single
+// source of truth.
+//
+// Callers retain control of the jobId via `options` — the resume-token-as-
+// jobId convention lives in stream.js, not here, because it depends on the
+// caller's choice of collection/operation namespace.
+
+const enqueueWithTrace = async ( queue, name, data, resumeToken, options = {} ) => {
+
+	const traceId = resumeToken?._data || String( resumeToken );
+
+	return queue.add(
+		name,
+		{
+			...data,
+			__traceId : traceId
+		},
+		options
+	);
+
+};
+
+export { enqueueWithTrace };

package/dist/stream.js

@@ -0,0 +1,15 @@
+// stream.js
+var enqueueWithTrace = async (queue, name, data, resumeToken, options = {}) => {
+  const traceId = (resumeToken == null ? void 0 : resumeToken._data) || String(resumeToken);
+  return queue.add(
+    name,
+    {
+      ...data,
+      __traceId: traceId
+    },
+    options
+  );
+};
+export {
+  enqueueWithTrace
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "type": "module",
+  "dependencies": {
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@sentry/core": ">=10"
+  },
+  "peerDependenciesMeta": {
+    "@sentry/core": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@sentry/core": "10.27.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js",
+      "require": "./dist/express.cjs"
+    },
+    "./bullmq": {
+      "types": "./dist/bullmq.d.ts",
+      "import": "./dist/bullmq.js",
+      "require": "./dist/bullmq.cjs"
+    },
+    "./stream": {
+      "types": "./dist/stream.d.ts",
+      "import": "./dist/stream.js",
+      "require": "./dist/stream.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "ISC",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "name": "@drawbridge/drawbridge-telemetry",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "sync": ". \"$HOME/.nvm/nvm.sh\" && nvm use && npm prune && npm install",
+    "build": "tsup && npm publish"
+  },
+  "types": "dist/index.d.ts",
+  "version": "0.0.1"
+}