feat(webapp): user-based Sentry attribution with tenant tags (#3678)

## Summary

Stamp every Sentry event with the signed-in user and the tenant (org /
project / env) the request belongs to, so "Users Impacted" counts
distinct humans and events become filterable per tenant.

**Design after review (current):**

- `user.id = real user cuid` (from `requireUser`). "Users Impacted"
counts humans, not tenants.
- Tenant context (org / project / env slugs, IDs, env type) moves
entirely onto tags: `org_slug`, `project_slug`, `env_slug`, `org_id`,
`project_id`, `project_ref`, `environment_id`, `env_type`, plus
`impersonating` when set.
- Backed by an `AsyncLocalStorage` scope established at the HTTP entry.
Each entry point fills what it knows; loaders enrich the same scope with
what they already have.

**Zero new database queries.** The middleware does a regex match only.
Dashboard loaders that already query Prisma gain a couple of extra
selected columns; nothing new round-trips.

## How it's wired

- **Express middleware (`tenantContextResolver.server.ts`)** — parses
the URL with a regex and always opens an ALS scope. Populates whatever
subset of slugs is present: `/orgs/:o` → just `orgSlug`;
`/orgs/:o/projects/:p` adds `projectSlug`; the full triple adds
`envSlug`. Non-tenant paths get an empty scope so loaders can still
enrich.
- **`_app/route.tsx`** — already calls `requireUser`. Adds
`tenantContext.enrich({ userId: user.id })` for every authenticated
dashboard request. No new query.
- **Env layout loader (`_app.orgs.$o.projects.$p.env.$e/route.tsx`)** —
its existing `prisma.project.findFirst` gains two columns in `select`
(`externalRef`, `organization.id`). After it picks an env, calls
`tenantContext.enrich({ orgId, projectId, projectRef, envId, envType
})`. Same query, +2 columns.
- **API path (`apiBuilder.server.ts`)** — wraps every handler in
`tenantContext.run(tenantContextFromAuthEnvironment(authenticationResult.environment),
…)`. The mapper pulls `userId` from `env.orgMember?.userId` (already
selected by `authIncludeBase` — no schema change). Covers
`createLoaderApiRoute`, `createActionApiRoute`, and
`createMultiMethodApiRoute`.
- **Event processor (`sentryTenantContext.server.ts`)** — registered in
`entry.server.tsx` so it lives in the Remix bundle and shares the same
`tenantContext` ALS instance as the middleware and loaders. Stamps
whatever's present; nothing forced.

## Example events from local verification

| URL | `user.id` | Tags |
|-----|-----------|------|
| `/orgs/:o/projects/:p/env/:e/...` | real user cuid | `org_slug`,
`project_slug`, `env_slug`, `org_id`, `project_id`, `project_ref`,
`environment_id`, `env_type` |
| `/orgs/:o/settings` (non-env-scoped) | real user cuid | `org_slug`
only |
| API request with `orgMember` | `orgMember.userId` | full tenant set |
| API request without `orgMember` | (unset) | full tenant set |

## Trade-offs

1. On env-scoped pages, errors that fire before the env layout loader's
enrich callback runs get slugs + `user.id` but not the tenant IDs /
`env_type`. Realistic errors deep in async work get the full set. (Same
race as before, narrower window now that slugs/`user.id` are populated
up-front by the middleware and `_app` enrich.)
2. API requests where the environment has no `orgMember` get tenant tags
but no `user.id`. Those events still show in the issue but don't
contribute to "Users Impacted".

## Out of scope (deferred)

Background workers (`redis-worker`, `schedule-engine`) and socket
handlers. Those entry points don't set `tenantContext.run` yet — their
events ship without tenant attribution until each is wired in a
follow-up.

## Tests

31 unit tests across 4 files. New tests notably cover:

- `parseTenantPath`: org-only, org+project, and full-triple URL
variants.
- `tenantContext.enrich`: in-place patch, no-op outside `run()`,
concurrent-scope isolation, empty-scope + enrich pattern (for non-tenant
pages).
- `tenantContextFromAuthEnvironment`: with and without `orgMember` —
verifies the API path's `user.id` mapping.
- `addTenantContextToEvent`: empty scope, userId-only, slugs-only, full
enrichment, conditional tag emission, preservation of prior `event.user`
fields.

## Test plan

- [ ] `pnpm run typecheck --filter webapp`
- [ ] `pnpm run test --filter webapp -- test/tenantContext.test.ts
test/sentryTenantContext.test.ts test/tenantContextResolver.test.ts
test/tenantContextFromAuthEnvironment.test.ts`
- [ ] Local manual: with `SENTRY_DSN` set, hit a dashboard URL and an
API route, confirm the captured events carry `user.id` + the expected
tag set in Sentry.
- [ ] After ship: confirm "Users Impacted" on a real Sentry issue
reflects distinct users (not tenants).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: d-cs

.server-changes/sentry-tenant-attribution.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Stamp Sentry events with the signed-in user so "Users Impacted" counts individual humans, and enrich events with org / project / environment tags when that context is available (dashboard URLs, authenticated API requests).

apps/webapp/app/entry.server.tsx

@@ -1,6 +1,8 @@
 import { createReadableStreamFromReadable, type EntryContext } from "@remix-run/node"; // or cloudflare/deno
 import { RemixServer } from "@remix-run/react";
+import * as Sentry from "@sentry/remix";
 import { wrapHandleErrorWithSentry } from "@sentry/remix";
+import { addTenantContextToEvent } from "~/utils/sentryTenantContext.server";
 import { parseAcceptLanguage } from "intl-parse-accept-language";
 import isbot from "isbot";
 import { renderToPipeableStream } from "react-dom/server";
@@ -257,9 +259,24 @@ process.on("uncaughtException", (error, origin) => {
 singleton("RunEngineEventBusHandlers", registerRunEngineEventBusHandlers);
 singleton("SetupBatchQueueCallbacks", setupBatchQueueCallbacks);
 
+// Wrapped in singleton() so Remix's dev-mode CJS reloads don't append
+// duplicate copies of the processor — Sentry's processor list lives in
+// node_modules and persists across module reloads. Idempotent at runtime
+// (the processor is a pure read+stamp), but the pattern matches the rest
+// of this file.
+singleton("SentryTenantContextProcessor", () => {
+  if (env.SENTRY_DSN) {
+    Sentry.addEventProcessor(addTenantContextToEvent);
+  }
+  // Return a truthy value — `singleton()` uses `??=` so a `void`
+  // callback would re-execute (and re-register) on every dev reload.
+  return true;
+});
+
 export { apiRateLimiter } from "./services/apiRateLimit.server";
 export { engineRateLimiter } from "./services/engineRateLimit.server";
 export { runWithHttpContext } from "./services/httpAsyncStorage.server";
+export { tenantContextMiddleware } from "./services/tenantContextResolver.server";
 export { socketIo } from "./v3/handleSocketIo.server";
 export { wss } from "./v3/handleWebsockets.server";
 

apps/webapp/app/env.server.ts

@@ -134,6 +134,7 @@ const EnvironmentSchema = z
     ELECTRIC_ORIGIN_SHARDS: z.string().optional(),
     APP_ENV: z.string().default(process.env.NODE_ENV),
     SERVICE_NAME: z.string().default("trigger.dev webapp"),
+    SENTRY_DSN: z.string().optional(),
     POSTHOG_PROJECT_KEY: z.string().default("phc_LFH7kJiGhdIlnO22hTAKgHpaKhpM8gkzWAFvHmf5vfS"),
     TRIGGER_TELEMETRY_DISABLED: z.string().optional(),
     AUTH_GITHUB_CLIENT_ID: z.string().optional(),

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam/route.tsx

@@ -5,6 +5,7 @@ import { redirectWithErrorMessage } from "~/models/message.server";
 import { updateCurrentProjectEnvironmentId } from "~/services/dashboardPreferences.server";
 import { logger } from "~/services/logger.server";
 import { requireUser } from "~/services/session.server";
+import { tenantContext } from "~/services/tenantContext.server";
 import { EnvironmentParamSchema, v3ProjectPath } from "~/utils/pathBuilder";
 
 export const loader = async ({ request, params }: LoaderFunctionArgs) => {
@@ -26,6 +27,8 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
     },
     select: {
       id: true,
+      externalRef: true,
+      organization: { select: { id: true } },
       environments: {
         select: {
           id: true,
@@ -52,6 +55,7 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
   }
 
   let environmentId: string | undefined = undefined;
+  let environmentType: "DEVELOPMENT" | "PREVIEW" | "STAGING" | "PRODUCTION" | undefined;
 
   if (environments.length > 1) {
     const bestEnvironment = environments.find((env) => env.orgMember?.userId === user.id);
@@ -63,10 +67,21 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
     }
 
     environmentId = bestEnvironment.id;
+    environmentType = bestEnvironment.type;
   } else {
     environmentId = environments[0].id;
+    environmentType = environments[0].type;
   }
 
+  // userId is enriched higher up in `_app/route.tsx`; only stamp tenant fields here.
+  tenantContext.enrich({
+    orgId: project.organization.id,
+    projectId: project.id,
+    projectRef: project.externalRef,
+    envId: environmentId,
+    envType: environmentType,
+  });
+
   await updateCurrentProjectEnvironmentId({ user: user, projectId: project.id, environmentId });
 
   return project;

apps/webapp/app/routes/_app/route.tsx

@@ -5,10 +5,12 @@ import { RouteErrorDisplay } from "~/components/ErrorDisplay";
 import { AppContainer, MainCenteredContainer } from "~/components/layout/AppLayout";
 import { clearRedirectTo, commitSession } from "~/services/redirectTo.server";
 import { requireUser } from "~/services/session.server";
+import { tenantContext } from "~/services/tenantContext.server";
 import { confirmBasicDetailsPath } from "~/utils/pathBuilder";
 
 export const loader = async ({ request }: LoaderFunctionArgs) => {
   const user = await requireUser(request);
+  tenantContext.enrich({ userId: user.id });
 
   //you have to confirm basic details before you can do anything
   if (!user.confirmedBasicDetails) {

apps/webapp/app/services/routeBuilders/apiBuilder.server.ts

@@ -19,6 +19,10 @@ import { API_VERSIONS, getApiVersion } from "~/api/versions";
 import { WORKER_HEADERS } from "@trigger.dev/core/v3/runEngineWorker";
 import { ServiceValidationError } from "~/v3/services/common.server";
 import { EngineServiceValidationError } from "@internal/run-engine";
+import {
+  tenantContext,
+  tenantContextFromAuthEnvironment,
+} from "~/services/tenantContext.server";
 
 // Client aborts and service-level validation errors aren't bugs — they're
 // expected at API boundaries. Log them at `warn` so they stay in stdout
@@ -357,15 +361,19 @@ export function createLoaderApiRoute<
 
       const apiVersion = getApiVersion(request);
 
-      const result = await handler({
-        params: parsedParams,
-        searchParams: parsedSearchParams,
-        headers: parsedHeaders,
-        authentication: authenticationResult,
-        request,
-        resource,
-        apiVersion,
-      });
+      const result = await tenantContext.run(
+        tenantContextFromAuthEnvironment(authenticationResult.environment),
+        () =>
+          handler({
+            params: parsedParams,
+            searchParams: parsedSearchParams,
+            headers: parsedHeaders,
+            authentication: authenticationResult,
+            request,
+            resource,
+            apiVersion,
+          })
+      );
       return await wrapResponse(request, result, corsStrategy !== "none");
     } catch (error) {
       try {
@@ -586,6 +594,11 @@ export function createLoaderPATApiRoute<
         }
       }
 
+      // PAT auth carries `userId` but no environment — enrich the scope
+      // the Express middleware established with the authenticated user so
+      // Sentry events from this handler get user-level attribution.
+      tenantContext.enrich({ userId: authenticationResult.userId });
+
       const result = await handler({
         params: parsedParams,
         searchParams: parsedSearchParams,
@@ -903,15 +916,19 @@ export function createActionApiRoute<
         );
       }
 
-      const result = await handler({
-        params: parsedParams,
-        searchParams: parsedSearchParams,
-        headers: parsedHeaders,
-        body: parsedBody,
-        authentication: authenticationResult,
-        request,
-        resource,
-      });
+      const result = await tenantContext.run(
+        tenantContextFromAuthEnvironment(authenticationResult.environment),
+        () =>
+          handler({
+            params: parsedParams,
+            searchParams: parsedSearchParams,
+            headers: parsedHeaders,
+            body: parsedBody,
+            authentication: authenticationResult,
+            request,
+            resource,
+          })
+      );
       return await wrapResponse(request, result, corsStrategy !== "none");
     } catch (error) {
       try {
@@ -1156,14 +1173,18 @@ export function createMultiMethodApiRoute<
       }
 
       // Dispatch to method handler
-      const result = await methodConfig.handler({
-        params: parsedParams,
-        searchParams: parsedSearchParams,
-        headers: parsedHeaders,
-        body: parsedBody,
-        authentication: authenticationResult,
-        request,
-      });
+      const result = await tenantContext.run(
+        tenantContextFromAuthEnvironment(authenticationResult.environment),
+        () =>
+          methodConfig.handler({
+            params: parsedParams,
+            searchParams: parsedSearchParams,
+            headers: parsedHeaders,
+            body: parsedBody,
+            authentication: authenticationResult,
+            request,
+          })
+      );
       return await wrapResponse(request, result, corsStrategy !== "none");
     } catch (error) {
       try {

apps/webapp/app/services/tenantContext.server.ts

@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { AuthenticatedEnvironment } from "./apiAuth.server";
+
+// All fields are optional. The middleware establishes an empty scope per
+// request; entry points fill what they know:
+//   - URL-matching paths get the slug trio from the Express middleware (zero IO).
+//   - The `_app` layout adds `userId` for any authenticated request.
+//   - The env layout adds tenant IDs / env type after its own existing DB query.
+//   - API routes get the full set up-front from `authenticationResult.environment`.
+export type TenantContext = {
+  userId?: string;
+  orgSlug?: string;
+  projectSlug?: string;
+  envSlug?: string;
+  orgId?: string;
+  projectId?: string;
+  projectRef?: string;
+  envId?: string;
+  envType?: "DEVELOPMENT" | "PREVIEW" | "STAGING" | "PRODUCTION";
+  impersonating?: boolean;
+};
+
+const storage = new AsyncLocalStorage<TenantContext>();
+
+export const tenantContext = {
+  run<T>(ctx: TenantContext, fn: () => T): T {
+    return storage.run(ctx, fn);
+  },
+  get(): TenantContext | undefined {
+    return storage.getStore();
+  },
+  enrich(patch: Partial<TenantContext>): void {
+    const current = storage.getStore();
+    if (current) Object.assign(current, patch);
+  },
+};
+
+export function tenantContextFromAuthEnvironment(env: AuthenticatedEnvironment): TenantContext {
+  return {
+    userId: env.orgMember?.userId,
+    orgSlug: env.organization.slug,
+    projectSlug: env.project.slug,
+    envSlug: env.slug,
+    orgId: env.organization.id,
+    projectId: env.project.id,
+    projectRef: env.project.externalRef,
+    envId: env.id,
+    envType: env.type,
+  };
+}

apps/webapp/app/services/tenantContextResolver.server.ts

@@ -0,0 +1,42 @@
+import type { NextFunction, Request, Response } from "express";
+import { tenantContext, type TenantContext } from "./tenantContext.server";
+
+const URL_PATTERN = /^\/orgs\/([^/]+)(?:\/projects\/([^/]+)(?:\/env\/([^/]+))?)?/;
+
+export type ParsedTenantPath = {
+  orgSlug: string;
+  projectSlug?: string;
+  envSlug?: string;
+};
+
+// Pulls whatever tenant slugs are present in the URL. `/orgs/:o` returns the
+// org alone; `/orgs/:o/projects/:p` adds the project; `/orgs/:o/projects/:p/env/:e`
+// returns all three. Non-tenant paths (`/`, `/login`, `/admin/*`) return undefined.
+export function parseTenantPath(pathname: string): ParsedTenantPath | undefined {
+  const match = pathname.match(URL_PATTERN);
+  if (!match) return undefined;
+  const [, orgSlug, projectSlug, envSlug] = match;
+  if (!orgSlug) return undefined;
+  return {
+    orgSlug,
+    ...(projectSlug ? { projectSlug } : {}),
+    ...(envSlug ? { envSlug } : {}),
+  };
+}
+
+export function resolveTenantContextFromPath(pathname: string): TenantContext {
+  return parseTenantPath(pathname) ?? {};
+}
+
+export type PathResolver = (pathname: string) => TenantContext;
+
+export function createTenantContextMiddleware(resolver: PathResolver) {
+  // Always establish an ALS scope, even when the path carries no tenant
+  // slugs. Authenticated loaders (e.g. the `_app` layout) then enrich the
+  // same scope with `userId`, so non-tenant pages still get user attribution.
+  return function tenantContextMiddleware(req: Request, res: Response, next: NextFunction) {
+    tenantContext.run(resolver(req.path), () => next());
+  };
+}
+
+export const tenantContextMiddleware = createTenantContextMiddleware(resolveTenantContextFromPath);

apps/webapp/app/utils/sentryTenantContext.server.ts

@@ -0,0 +1,26 @@
+import type { Event, EventHint } from "@sentry/remix";
+import { tenantContext } from "../services/tenantContext.server";
+
+export function addTenantContextToEvent(event: Event, _hint: EventHint): Event {
+  const ctx = tenantContext.get();
+  if (!ctx) return event;
+  return {
+    ...event,
+    // Only stamp user.id when we have a real user — keeps "Users Impacted"
+    // counting distinct humans rather than mixing in tenants. Events without
+    // a known user (e.g. unauthenticated paths) skip user attribution.
+    ...(ctx.userId ? { user: { ...event.user, id: ctx.userId } } : {}),
+    tags: {
+      ...event.tags,
+      ...(ctx.orgSlug ? { org_slug: ctx.orgSlug } : {}),
+      ...(ctx.projectSlug ? { project_slug: ctx.projectSlug } : {}),
+      ...(ctx.envSlug ? { env_slug: ctx.envSlug } : {}),
+      ...(ctx.orgId ? { org_id: ctx.orgId } : {}),
+      ...(ctx.projectId ? { project_id: ctx.projectId } : {}),
+      ...(ctx.projectRef ? { project_ref: ctx.projectRef } : {}),
+      ...(ctx.envId ? { environment_id: ctx.envId } : {}),
+      ...(ctx.envType ? { env_type: ctx.envType } : {}),
+      ...(ctx.impersonating ? { impersonating: "true" } : {}),
+    },
+  };
+}

apps/webapp/server.ts

@@ -122,6 +122,8 @@ if (ENABLE_CLUSTER && cluster.isPrimary) {
     const apiRateLimiter: RateLimitMiddleware = build.entry.module.apiRateLimiter;
     const engineRateLimiter: RateLimitMiddleware = build.entry.module.engineRateLimiter;
     const runWithHttpContext: RunWithHttpContextFunction = build.entry.module.runWithHttpContext;
+    const tenantContextMiddleware: import("express").RequestHandler =
+      build.entry.module.tenantContextMiddleware;
 
     app.use((req, res, next) => {
       // helpful headers:
@@ -171,6 +173,8 @@ if (ENABLE_CLUSTER && cluster.isPrimary) {
       app.use(apiRateLimiter);
       app.use(engineRateLimiter);
 
+      app.use(tenantContextMiddleware);
+
       app.all(
         "*",
         // @ts-ignore