feat(observability): fan-out errors Sentry + PostHog + opt-in flags (#3489)

* feat(observability): fan-out errors Sentry + PostHog + opt-in flags (#3486)

- New `lib/services/errorTracker.js`: `captureException(err, ctx)` fans out to
  Sentry (if dsn) and PostHog (if apiKey + errorTracking===true). Silent no-op
  when neither is configured. `setupExpressErrorHandler` replaces the previous
  Sentry-only wiring in express.js.
- `analytics.js`: add `captureException(err, ctx)` — sends PostHog `$exception`
  event with message, type, stack, requestId.
- `express.js`: gate `analyticsMiddleware` behind `posthog.autoCapture===true`
  (was unconditionally mounted); replace `sentry.setupExpressErrorHandler` with
  `errorTracker.setupExpressErrorHandler` (Sentry handler + fan-out middleware).
- Config defaults: add `posthog.errorTracking: false` and `posthog.autoCapture:
  false` explicit opt-in flags — default-safe invariant.
- Tests: 11 unit tests covering all 4 tracker combinations + init + Express
  middleware, including default-safe invariant verification.

Closes #3486

* test(analytics): add captureException unit tests for 100% patch coverage

Add 4 tests covering captureException: correct $exception event payload,
anonymous fallback distinctId, no-op when client not initialised, and
silent error swallowing. Ensures codecov/patch threshold is met.

* fix(observability): address CodeRabbit review — no double-Sentry, _res rename, req.user._id

- `errorTracker.js`: add `captureExceptionPostHogOnly` to avoid double-reporting
  to Sentry in the Express error middleware (Sentry already captured via its own
  handler). Rename unused `res` to `_res`. Derive `distinctId` from
  `req.user._id` / `req.user.id` (not the non-existent `req.userId`).
- Tests: update setupExpressErrorHandler test to verify Sentry is NOT called
  from middleware. Add 2 new tests for req.user.id fallback and anonymous.

Author: PierreBrisorgueil

config/defaults/development.config.js

@@ -87,6 +87,8 @@ const config = {
   posthog: {
     // apiKey: process.env.DEVKIT_NODE_posthog_apiKey ?? '',
     // host: process.env.DEVKIT_NODE_posthog_host ?? 'https://us.i.posthog.com',
+    errorTracking: false, // opt-in: capture exceptions to PostHog (default: off)
+    autoCapture: false, // opt-in: auto-capture api_request events (default: off)
   },
   domain: '',
   cookie: {

lib/services/analytics.js

@@ -93,6 +93,34 @@ const isFeatureEnabled = async (flag, distinctId, options) => {
   return client.isFeatureEnabled(flag, distinctId, options);
 };
 
+/**
+ * Capture an exception event in PostHog.
+ * Only active when `errorTracking` is opted-in via config — the caller
+ * (`errorTracker.js`) is responsible for checking the flag before calling.
+ * Safe to call when the PostHog client was never initialised.
+ * @param {Error} err - Error to capture
+ * @param {Object} [ctx] - Optional context attached to the event
+ * @param {string} [ctx.distinctId] - User identifier
+ * @param {string} [ctx.requestId] - Request trace ID
+ * @returns {void}
+ */
+const captureException = (err, ctx = {}) => {
+  if (!client) return;
+  try {
+    const distinctId = ctx.distinctId || 'anonymous';
+    client.capture({
+      distinctId,
+      event: '$exception',
+      properties: {
+        $exception_message: err?.message,
+        $exception_type: err?.name,
+        $exception_stack: err?.stack,
+        requestId: ctx.requestId,
+      },
+    });
+  } catch (_) { /* analytics must never break caller */ }
+};
+
 /**
  * Flush pending events and shut down the PostHog client.
  * Safe to call even when the client was never initialised.
@@ -111,5 +139,6 @@ export default {
   groupIdentify,
   getFeatureFlag,
   isFeatureEnabled,
+  captureException,
   shutdown,
 };

lib/services/errorTracker.js

@@ -0,0 +1,98 @@
+/**
+ * Module dependencies
+ */
+import config from '../../config/index.js';
+import sentryService from './sentry.js';
+import analyticsService from './analytics.js';
+
+/**
+ * Capture an exception, fanning out to all active trackers.
+ *
+ * - Sentry  : active when `config.sentry.dsn` is set (and `enabled !== false`)
+ * - PostHog : active when `config.posthog.apiKey` is set AND
+ *             `config.posthog.errorTracking === true`
+ *
+ * Safe no-op when neither tracker is configured.
+ *
+ * @param {Error} err - Error to capture
+ * @param {Object} [ctx] - Optional context attached to the event
+ * @param {string} [ctx.distinctId] - User identifier for PostHog
+ * @param {string} [ctx.requestId] - Request trace ID
+ * @returns {void}
+ */
+const captureException = (err, ctx = {}) => {
+  // Sentry fan-out
+  const sentryConfig = config?.sentry ?? {};
+  if (sentryConfig.dsn && sentryConfig.enabled !== false) {
+    sentryService.captureException(err);
+  }
+
+  // PostHog fan-out — only when errorTracking is explicitly opted-in
+  const posthogConfig = config?.posthog ?? {};
+  if (posthogConfig.apiKey && posthogConfig.errorTracking === true) {
+    analyticsService.captureException(err, ctx);
+  }
+};
+
+/**
+ * Capture an exception in PostHog only (skips Sentry).
+ * Used inside the Express error middleware where Sentry's own Express handler
+ * has already reported the error — calling captureException() here would
+ * report it to Sentry a second time.
+ *
+ * @param {Error} err - Error to capture
+ * @param {Object} [ctx] - Optional context
+ * @returns {void}
+ */
+const captureExceptionPostHogOnly = (err, ctx = {}) => {
+  const posthogConfig = config?.posthog ?? {};
+  if (posthogConfig.apiKey && posthogConfig.errorTracking === true) {
+    analyticsService.captureException(err, ctx);
+  }
+};
+
+/**
+ * Initialise all configured trackers (Sentry + PostHog).
+ * Safe to call when neither is configured.
+ * @returns {Promise<void>}
+ */
+const init = async () => {
+  await Promise.all([
+    sentryService.init(),
+    analyticsService.init(),
+  ]);
+};
+
+/**
+ * Set up Express error handling for all active trackers.
+ *
+ * Must be called after all routes are mounted.
+ * Mounts Sentry's Express error handler first (captures structured request
+ * context), then a PostHog-only fan-out middleware to avoid double-reporting
+ * to Sentry (which is already covered by Sentry's own Express handler).
+ *
+ * @param {import('express').Express} app - Express application instance
+ */
+const setupExpressErrorHandler = (app) => {
+  // Sentry Express handler (structured request/response context)
+  sentryService.setupExpressErrorHandler(app);
+
+  // PostHog-only fan-out middleware — Sentry already handled above
+  // `_res` is required for Express to recognise this as a 4-arg error handler
+  app.use((err, req, _res, next) => {
+    const distinctId = req.user?._id
+      ? String(req.user._id)
+      : req.user?.id
+        ? String(req.user.id)
+        : 'anonymous';
+    captureExceptionPostHogOnly(err, { distinctId, requestId: req.id });
+    next(err);
+  });
+};
+
+export default {
+  init,
+  captureException,
+  captureExceptionPostHogOnly,
+  setupExpressErrorHandler,
+};

lib/services/express.js

@@ -21,7 +21,7 @@ import config from '../../config/index.js';
 import guidesHelper from '../helpers/guides.js';
 import logger from './logger.js';
 import requestId from '../middlewares/requestId.js';
-import sentry from './sentry.js';
+import errorTracker from './errorTracker.js';
 import AnalyticsService from './analytics.js';
 import analyticsMiddleware from '../middlewares/analytics.js';
 
@@ -288,12 +288,15 @@ const init = async () => {
   app.use(requestId);
   // Initialize pre-parser routes (before body parsing, CSRF, and analytics)
   await initPreParserRoutes(app);
-  // Initialize analytics (PostHog) and mount auto-capture middleware
-  // Mounted after pre-parser routes so webhooks are not tracked
-  // Wrapped in try/catch so analytics failures never prevent app startup
+  // Initialize analytics (PostHog).
+  // Mounted after pre-parser routes so webhooks are not tracked.
+  // Wrapped in try/catch so analytics failures never prevent app startup.
+  // auto-capture middleware is opt-in: only mounted when posthog.autoCapture === true.
   try {
     await AnalyticsService.init();
-    app.use(analyticsMiddleware);
+    if (config.posthog?.autoCapture === true) {
+      app.use(analyticsMiddleware);
+    }
   } catch (err) {
     logger.warn('[analytics] init failed, running without analytics: %s', err.message);
   }
@@ -311,8 +314,8 @@ const init = async () => {
   await initModulesServerPolicies(app);
   // Initialize modules server routes
   await initModulesServerRoutes(app);
-  // Mount Sentry error handler (must be after routes, before generic error handler)
-  sentry.setupExpressErrorHandler(app);
+  // Mount error tracker handler (Sentry + fan-out) — must be after routes
+  errorTracker.setupExpressErrorHandler(app);
   // Initialize error routes
   initErrorRoutes(app);
   return app;

lib/services/tests/analytics.service.unit.tests.js

@@ -236,5 +236,58 @@ describe('Analytics service unit tests:', () => {
       AnalyticsService.track('user-1', 'test');
       expect(mockPostHogInstance.capture).not.toHaveBeenCalled();
     });
+
+    test('captureException should send $exception event with correct properties', async () => {
+      const mod = await import('../analytics.js');
+      AnalyticsService = mod.default;
+
+      await AnalyticsService.init();
+      const err = new Error('test error');
+      err.stack = 'Error: test error\n  at test.js:1:1';
+      AnalyticsService.captureException(err, { distinctId: 'user-1', requestId: 'req-abc' });
+
+      expect(mockPostHogInstance.capture).toHaveBeenCalledWith({
+        distinctId: 'user-1',
+        event: '$exception',
+        properties: {
+          $exception_message: 'test error',
+          $exception_type: 'Error',
+          $exception_stack: err.stack,
+          requestId: 'req-abc',
+        },
+      });
+    });
+
+    test('captureException should use anonymous distinctId when not provided', async () => {
+      const mod = await import('../analytics.js');
+      AnalyticsService = mod.default;
+
+      await AnalyticsService.init();
+      AnalyticsService.captureException(new Error('anon error'), {});
+
+      expect(mockPostHogInstance.capture).toHaveBeenCalledWith(
+        expect.objectContaining({ distinctId: 'anonymous' }),
+      );
+    });
+
+    test('captureException should be a no-op when client is not initialised', async () => {
+      const mod = await import('../analytics.js');
+      AnalyticsService = mod.default;
+
+      // Do NOT call init — client stays null
+      AnalyticsService.captureException(new Error('no client'), { distinctId: 'user-1' });
+      expect(mockPostHogInstance.capture).not.toHaveBeenCalled();
+    });
+
+    test('captureException should silently swallow client errors', async () => {
+      const mod = await import('../analytics.js');
+      AnalyticsService = mod.default;
+
+      await AnalyticsService.init();
+      mockPostHogInstance.capture.mockImplementation(() => { throw new Error('client error'); });
+
+      // Should not throw
+      expect(() => AnalyticsService.captureException(new Error('err'), {})).not.toThrow();
+    });
   });
 });