feat(observability): correlate Loki logs + GlitchTip events by user.id (#47)

Closes the last missing piece of UI ↔ API ↔ GlitchTip ↔ Loki
correlation: every error event and every log line now carries the
user's identity, and Grafana log lines have one-click data links into
the matching GlitchTip search.

API (apps/api):
- auth.plugin.ts: once the auth middleware resolves the user from the
  cookie, call `Sentry.setUser({ id, email })` on the request-scoped
  Sentry scope. Any error captured for the remainder of the request
  carries `user.id` + `user.email` tags. No-op when SENTRY_DSN is unset.
- logger.ts: the Pino mixin already injects trace_id + span_id from the
  active Sentry span on every log record; it now also reads userId
  from `Sentry.getCurrentScope().getUser()?.id` and emits it alongside.
  Unauthenticated requests get a trace id but no userId, and everything
  short-circuits to `{}` when Sentry isn't initialised.

UI (apps/ui):
- New SentryUserSync provider component: watches the useMe query and
  calls `Sentry.setUser({ id, email })` whenever the current user
  changes, `Sentry.setUser(null)` when the session goes away. Covers
  every entry path uniformly (fresh login, MFA verify, account switch,
  page-reload with an existing session) without having to remember to
  call setUser in each mutation. Mounted as a sibling of AbilityProvider.

Promtail (infra/compose):
- userId is now parsed out of the Pino JSON expressions block and
  promoted to Loki structured metadata alongside requestId / trace_id /
  span_id. Lets LogQL queries filter by user without a `| json` reparse.

Grafana — API logs dashboard:
- Two textbox variables (`$glitchtip_url`, `$glitchtip_org`) with dev
  defaults of `http://glitchtip.localhost` and `local`. One edit per
  environment if you point your stack at a different GlitchTip host.
- Data links on three structured-metadata fields in the Application
  logs panel:
    • trace_id → opens `${glitchtip_url}/${glitchtip_org}/issues/
                       ?query=trace_id:<value>` in a new tab
    • userId   → opens `…?query=user.id:<value>` in a new tab
    • requestId → opens Grafana Explore pre-filtered to that
                  request's lines via a Loki `|=` query
- Result: expand any log line → one click to GlitchTip search by
  trace, by user, or back to Loki by request id. Browser → API → DB
  is now a single round-trip in the dashboards.

The matching Sentry side (GlitchTip event detail) shows the same
trace_id + user.id as tags; a `tags.trace_id` external-link template
configured once in GlitchTip's project settings (UI; not code) closes
the loop back to Grafana Loki for the inverse pivot.

Verification: API bun run validate green (997 pass / 2 skip / 0 fail);
UI bun run validate green (495 pass, size-check + bundle-check clean);
all 5 dashboards pass `python -m json.tool`; promtail-config.yml
validates against `grafana/promtail:3.2.1 -check-syntax`.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: agjs

apps/api/src/api/auth/auth.plugin.ts

@@ -1,3 +1,4 @@
+import * as Sentry from "@sentry/bun";
 import { eq } from "drizzle-orm";
 import { Elysia } from "elysia";
 
@@ -118,6 +119,16 @@ export const createAuthMiddleware = () =>
             throw ApiErrors.unauthorized("User not found");
           }
 
+          /*
+           * Tag the active Sentry scope with the user so any error
+           * captured for the rest of this request carries `user.id` +
+           * `user.email`. The Pino mixin also reads this scope to inject
+           * `userId` on every log record, so a Grafana log line and a
+           * GlitchTip error event can be correlated by the same id.
+           * No-op when SENTRY_DSN is unset.
+           */
+          Sentry.setUser({ id: user.id, email: user.email });
+
           return { user, accountId: parsed.accountId };
         } catch (err: unknown) {
           return translateJwtError(err);

apps/api/src/config/logger/logger.ts

@@ -6,21 +6,37 @@ import type { LOG_EVENTS } from "./logger.events";
 type ILogEventName = (typeof LOG_EVENTS)[number];
 
 /*
- * Inject the current Sentry/OTel span's trace_id + span_id on every log
- * record. Promtail extracts these as Loki structured metadata so a log
- * line surfaced in Grafana can be pivoted to its trace in Sentry/GlitchTip
- * by the same id. Returns {} when no span is active.
+ * Inject Sentry-scoped correlation fields on every log record:
+ *   - trace_id + span_id from the active Sentry/OTel span
+ *   - userId from the current scope (set by auth.plugin.ts after the
+ *     user is resolved on an authenticated request)
+ *
+ * Promtail extracts these as Loki structured metadata so a log line
+ * surfaced in Grafana can be pivoted to its trace or its user in
+ * Sentry/GlitchTip by the same id. Each field is a no-op when its
+ * source isn't set — unauthenticated requests get trace ids but no
+ * userId; everything is `{}` before Sentry.init when no DSN is
+ * configured.
  */
 const traceMixin = (): Record<string, string> => {
+  const fields: Record<string, string> = {};
+
   const span = Sentry.getActiveSpan();
 
-  if (span === undefined) {
-    return {};
+  if (span !== undefined) {
+    const ctx = span.spanContext();
+
+    fields.trace_id = ctx.traceId;
+    fields.span_id = ctx.spanId;
   }
 
-  const ctx = span.spanContext();
+  const userId = Sentry.getCurrentScope().getUser()?.id;
+
+  if (userId !== undefined) {
+    fields.userId = String(userId);
+  }
 
-  return { trace_id: ctx.traceId, span_id: ctx.spanId };
+  return fields;
 };
 
 /*

apps/ui/src/app/App.tsx

@@ -8,6 +8,7 @@ import { AbilityProvider } from "./providers/AbilityProvider";
 import { ErrorBoundaryProvider } from "./providers/ErrorBoundaryProvider";
 import { I18nProvider } from "./providers/I18nProvider";
 import { QueryProvider } from "./providers/QueryProvider";
+import { SentryUserSync } from "./providers/SentryUserSync";
 import { ToastProvider } from "./providers/ToastProvider";
 import { AppRoutes } from "./router/routes";
 
@@ -19,6 +20,7 @@ export const App: FC = () => {
           <QueryProvider>
             <AbilityProvider>
               <ToastProvider>
+                <SentryUserSync />
                 <AppRoutes />
                 <CookieConsentBanner />
               </ToastProvider>

apps/ui/src/app/providers/SentryUserSync.tsx

@@ -0,0 +1,39 @@
+import { useEffect } from "react";
+
+import * as Sentry from "@sentry/react";
+
+import { useMe } from "@/features/auth/Auth.queries";
+
+/*
+ * Syncs the current /me identity into the Sentry SDK's user context so
+ * any error captured by Sentry/GlitchTip is tagged with the actual user
+ * (id + email). The matching `Sentry.setUser()` on the API side
+ * (auth.plugin.ts) gives the same correlation on the server, so a
+ * browser-side exception and the upstream API error appear under the
+ * same user.id in GlitchTip.
+ *
+ * Mounted as a sibling of AbilityProvider in App.tsx. No UI; purely a
+ * side-effect on every change to the current-user query result.
+ *
+ * No-op when VITE_SENTRY_DSN is empty — Sentry.init didn't run, the
+ * setUser call is a noop. Logout sets the user to null so subsequent
+ * unauthenticated errors aren't attributed to the last signed-in user.
+ */
+export const SentryUserSync = (): null => {
+  const me = useMe();
+
+  useEffect(() => {
+    if (me.data?.user) {
+      Sentry.setUser({
+        id: me.data.user.id,
+        email: me.data.user.email
+      });
+
+      return;
+    }
+
+    Sentry.setUser(null);
+  }, [me.data?.user]);
+
+  return null;
+};

infra/compose/compose/grafana/dashboards/boringstack-api-logs.json

@@ -279,7 +279,57 @@
     },
     {
       "datasource": { "type": "loki", "uid": "loki" },
-      "description": "Application events: request lifecycle, errors, business events. Drizzle's per-query SQL logs are filtered out — see the next panel for those. Click a line to expand structured metadata (trace_id, requestId).",
+      "description": "Application events: request lifecycle, errors, business events. Drizzle's per-query SQL logs are filtered out — see the next panel for those. Click a line to expand structured metadata: `trace_id` and `userId` are clickable and open the matching GlitchTip search in a new tab.",
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": [
+          {
+            "matcher": { "id": "byName", "options": "trace_id" },
+            "properties": [
+              {
+                "id": "links",
+                "value": [
+                  {
+                    "title": "Search this trace in GlitchTip",
+                    "url": "${glitchtip_url}/${glitchtip_org}/issues/?query=trace_id%3A${__value.raw}",
+                    "targetBlank": true
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "matcher": { "id": "byName", "options": "userId" },
+            "properties": [
+              {
+                "id": "links",
+                "value": [
+                  {
+                    "title": "Search this user in GlitchTip",
+                    "url": "${glitchtip_url}/${glitchtip_org}/issues/?query=user.id%3A${__value.raw}",
+                    "targetBlank": true
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "matcher": { "id": "byName", "options": "requestId" },
+            "properties": [
+              {
+                "id": "links",
+                "value": [
+                  {
+                    "title": "Filter Loki to this request",
+                    "url": "/explore?left=%7B%22datasource%22%3A%22loki%22%2C%22queries%22%3A%5B%7B%22refId%22%3A%22A%22%2C%22expr%22%3A%22%7Bcompose_service%3D~%5C%22api-dev%7Capi%5C%22%7D%20%7C%3D%20%5C%22${__value.raw}%5C%22%22%7D%5D%7D",
+                    "targetBlank": true
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      },
       "gridPos": { "h": 14, "w": 24, "x": 0, "y": 20 },
       "id": 8,
       "options": {
@@ -331,7 +381,30 @@
   "refresh": "10s",
   "schemaVersion": 39,
   "tags": ["boringstack", "api", "logs"],
-  "templating": { "list": [] },
+  "templating": {
+    "list": [
+      {
+        "current": { "text": "http://glitchtip.localhost", "value": "http://glitchtip.localhost" },
+        "hide": 0,
+        "label": "GlitchTip URL",
+        "name": "glitchtip_url",
+        "options": [{ "selected": true, "text": "http://glitchtip.localhost", "value": "http://glitchtip.localhost" }],
+        "query": "http://glitchtip.localhost",
+        "skipUrlSync": false,
+        "type": "textbox"
+      },
+      {
+        "current": { "text": "local", "value": "local" },
+        "hide": 0,
+        "label": "GlitchTip org slug",
+        "name": "glitchtip_org",
+        "options": [{ "selected": true, "text": "local", "value": "local" }],
+        "query": "local",
+        "skipUrlSync": false,
+        "type": "textbox"
+      }
+    ]
+  },
   "time": { "from": "now-30m", "to": "now" },
   "timepicker": {},
   "timezone": "",

infra/compose/compose/promtail/promtail-config.yml

@@ -79,6 +79,7 @@ scrape_configs:
             requestId: requestId
             trace_id: trace_id
             span_id: span_id
+            userId: userId
             msg: msg
       # Lowercase Pino's level ("INFO" → "info"). Promote as the `level`
       # label so Grafana's logs panel auto-colours each line by severity.
@@ -94,6 +95,7 @@ scrape_configs:
           requestId:
           trace_id:
           span_id:
+          userId:
       # Use Pino's `time` (epoch ms) as the log entry timestamp.
       - timestamp:
           source: time