feat(stdlib): add Sentry support

See the docs on `compasWithSentry` for more details

Author: dirkdev98

package-lock.json

@@ -92,3 +92,5 @@ export {
   eventStop,
   newEventFromEvent,
 } from "./src/events.js";
+
+export { _compasSentryExport, compasWithSentry } from "./src/sentry.js";

packages/stdlib/index.js

@@ -25,6 +25,9 @@
     "lodash.merge": "4.6.2",
     "pino": "8.20.0"
   },
+  "devDependencies": {
+    "@sentry/node": "^7.110.0"
+  },
   "author": {
     "name": "Dirk de Visser",
     "email": "npm@dirkdevisser.nl",

packages/stdlib/package.json

@@ -1,5 +1,6 @@
 import { AppError } from "./error.js";
 import { isNil } from "./lodash.js";
+import { _compasSentryExport } from "./sentry.js";
 
 /**
  * @typedef {object} InsightEventSpan
@@ -13,8 +14,8 @@ import { isNil } from "./lodash.js";
 
 /**
  * The insight event is a tool for tracking the duration of (async) functions manually.
- * By utilizing the insight event, you can gain access to a task or request-specific logger and
- * obtain insights into the execution time of your functions.
+ * By utilizing the insight event, you can gain access to a task or request-specific
+ * logger and obtain insights into the execution time of your functions.
  *
  * How to use the Insight Event:
  *
@@ -24,7 +25,8 @@ import { isNil } from "./lodash.js";
  * In your tests you can use {@link newTestEvent}.
  *
  * You could pass the event object down through your (async) functions as an argument.
- * This allows the insight event to associate the event with the specific task or request.
+ * This allows the insight event to associate the event with the specific task or
+ * request.
  *
  * Finally, you should stop the event for correct logging by calling {@link eventStop}.
  * When the root event is stopped via {@link eventStop} it calculates the duration
@@ -64,6 +66,7 @@ import { isNil } from "./lodash.js";
  * @property {InsightEvent} [rootEvent]
  * @property {string} [name]
  * @property {InsightEventSpan} span
+ * @property {import("@sentry/node").Span} [_compasSentrySpan]
  */
 
 /**
@@ -91,6 +94,8 @@ function InsightEventConstructor(logger, signal) {
       abortedTime: undefined,
       children: [],
     },
+
+    _compasSentrySpan: undefined,
   };
 }
 
@@ -120,6 +125,10 @@ export function newEventFromEvent(event) {
   if (event.signal?.aborted) {
     event.span.abortedTime = Date.now();
 
+    if (event._compasSentrySpan) {
+      event._compasSentrySpan.end();
+    }
+
     throw AppError.serverError({
       message: "Operation aborted",
       span: getEventRoot(event).span,
@@ -151,9 +160,21 @@ export function eventStart(event, name) {
   event.span.name = name;
   event.span.startTime = Date.now();
 
+  if (typeof _compasSentryExport?.startInactiveSpan === "function") {
+    event._compasSentrySpan = _compasSentryExport.startInactiveSpan({
+      op: "event",
+      name: name,
+      description: name,
+    });
+  }
+
   if (event.signal?.aborted) {
     event.span.abortedTime = Date.now();
 
+    if (event._compasSentrySpan) {
+      event._compasSentrySpan.end();
+    }
+
     throw AppError.serverError({
       message: "Operation aborted",
       span: getEventRoot(event).span,
@@ -174,9 +195,18 @@ export function eventRename(event, name) {
   event.name = name;
   event.span.name = name;
 
+  if (event._compasSentrySpan) {
+    event._compasSentrySpan.description = name;
+    event._compasSentrySpan.updateName(name);
+  }
+
   if (event.signal?.aborted) {
     event.span.abortedTime = Date.now();
 
+    if (event._compasSentrySpan) {
+      event._compasSentrySpan.end();
+    }
+
     throw AppError.serverError({
       message: "Operation aborted",
       span: getEventRoot(event).span,
@@ -199,6 +229,10 @@ export function eventStop(event) {
     event.span.duration = event.span.stopTime - event.span.startTime;
   }
 
+  if (event._compasSentrySpan) {
+    event._compasSentrySpan.end();
+  }
+
   if (isNil(event.rootEvent)) {
     event.log.info({
       type: "event_span",

packages/stdlib/src/events.js

@@ -3,6 +3,7 @@ import { environment, isProduction } from "./env.js";
 import { AppError } from "./error.js";
 import { isNil, isPlainObject, merge } from "./lodash.js";
 import { loggerWriteGithubActions, loggerWritePretty } from "./log-writers.js";
+import { _compasSentryExport } from "./sentry.js";
 
 /**
  * @typedef {object} Logger
@@ -123,6 +124,63 @@ export function newLogger(options) {
     context,
   });
 
+  if (typeof _compasSentryExport?.addBreadcrumb === "function") {
+    let addedContextAsBreadcrumb = false;
+
+    return {
+      info: (message) => {
+        if (!addedContextAsBreadcrumb) {
+          // @ts-expect-error
+          _compasSentryExport.addBreadcrumb({
+            category: context.type,
+            data: {
+              ...context,
+            },
+            level: "info",
+            type: "default",
+          });
+          addedContextAsBreadcrumb = true;
+        }
+
+        // @ts-expect-error
+        _compasSentryExport.addBreadcrumb({
+          category: context.type,
+          data: typeof message === "string" ? undefined : message,
+          message: typeof message === "string" ? message : undefined,
+          level: "info",
+          type: "default",
+        });
+
+        childLogger.info({ message });
+      },
+      error: (message) => {
+        if (!addedContextAsBreadcrumb) {
+          // @ts-expect-error
+          _compasSentryExport.addBreadcrumb({
+            category: "log",
+            data: {
+              ...context,
+            },
+            level: "info",
+            type: "default",
+          });
+          addedContextAsBreadcrumb = true;
+        }
+
+        // @ts-expect-error
+        _compasSentryExport.addBreadcrumb({
+          category: "log",
+          data: typeof message === "string" ? undefined : message,
+          message: typeof message === "string" ? message : undefined,
+          level: "error",
+          type: "error",
+        });
+
+        childLogger.error({ message });
+      },
+    };
+  }
+
   return {
     info: (message) => childLogger.info({ message }),
     error: (message) => childLogger.error({ message }),

packages/stdlib/src/logger.js

@@ -0,0 +1,40 @@
+/**
+ * The Sentry version that all Compas packages use if set via {@link compasWithSentry}.
+ *
+ * @type {undefined|import("@sentry/node")}
+ */
+export let _compasSentryExport = undefined;
+
+/**
+ * Enable Sentry support. This comes with the following changes:
+ *
+ * Stdlib:
+ * - Logger: both info and error logs are added as breadcrumbs to the current active span.
+ * - Event: Events are propagated to Sentry as (inactive) spans.
+ *     Meaning that further logs are not necessarily correlated to the correct event.
+ *     This can be inferred based on the timeline.
+ *
+ * Server:
+ * - Starts a new root span for each incoming request.
+ * - Tries to name it based on the finalized name of `ctx.event`.
+ *     This is most likely in the format `router.foo.bar` for matched routes by the generated router.
+ * - Uses the sentry-trace header when provided.
+ *     Note that if a custom list of `allowHeaders` is provided in the CORS options,
+ *     'sentry-trace' and 'baggage' should be allowed as well.
+ * - If the error handler retrieves an unknown or AppError.serverError, it is reported as an uncaught exception.
+ *     It is advised to set 'maxDepth' to '0' in your Sentry config, and to enable the 'extraErrorDataIntegration' integration.
+ *
+ * Queue:
+ * - Starts a new root span for each handled Job
+ * - Names it based on the job name.
+ * - Reports unhandled errors as exceptions.
+ *
+ * All:
+ * - Each package that has error logs, will report an exception as well.
+ * - Note that we still execute the logs for now. Which may be removed in a future release.
+ *
+ * @param {import("@sentry/node")} instance
+ */
+export function compasWithSentry(instance) {
+  _compasSentryExport = instance;
+}

packages/stdlib/src/sentry.js

@@ -9,9 +9,10 @@ import { AppError } from "./error.js";
 import { isNil } from "./lodash.js";
 import {
   loggerDetermineDefaultDestination,
-  newLogger,
   loggerExtendGlobalContext,
+  newLogger,
 } from "./logger.js";
+import { _compasSentryExport } from "./sentry.js";
 
 /**
  * Get the number of seconds since Unix epoch (1-1-1970).
@@ -97,30 +98,42 @@ export function mainFn(meta, cb) {
     process.exit(1);
   };
 
-  process.on("unhandledRejection", (reason, promise) =>
+  process.on("unhandledRejection", (reason, promise) => {
+    if (_compasSentryExport) {
+      _compasSentryExport.captureException(reason);
+    }
+
     unhandled({
       type: "unhandledRejection",
       reason: AppError.format(reason),
       promise,
-    }),
-  );
+    });
+  });
+
+  process.on("uncaughtException", (error, origin) => {
+    if (_compasSentryExport) {
+      _compasSentryExport.captureException(error);
+    }
 
-  process.on("uncaughtException", (error, origin) =>
     unhandled({
       type: "uncaughtException",
       error: AppError.format(error),
       origin,
-    }),
-  );
+    });
+  });
 
-  process.on("warning", (warn) =>
+  process.on("warning", (warn) => {
     logger.error({
       type: "warning",
       warning: AppError.format(warn),
-    }),
-  );
+    });
+  });
 
   Promise.resolve(cb(logger)).catch((e) => {
+    if (_compasSentryExport) {
+      _compasSentryExport.captureException(e);
+    }
+
     unhandled({
       type: "error",
       message: "Error caught from callback passed in `mainFn`",