feat(webapp): attach tenant context to Sentry events

Stamp each Sentry event with the org/project/env it belongs to so
"Users Impacted" reflects tenant count and events are filterable per
org. Uses an AsyncLocalStorage scope set at HTTP entry points (API
routes via apiBuilder, dashboard routes via an Express middleware that
resolves org/project/env from the URL).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: d-cs

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

@@ -0,0 +1,15 @@
+---
+area: webapp
+type: feature
+---
+
+Attach organization / project / environment to every Sentry event so "Users Impacted" counts orgs and events are filterable by tenant.
+
+Mechanism: `AsyncLocalStorage`-backed `tenantContext` + a Sentry `addEventProcessor` that stamps `user.id = orgId`, `user.username = orgSlug`, and tags (`org_id`, `org_slug`, `project_id`, `project_ref`, `environment_id`, `env_slug`, `env_type`, `impersonating`).
+
+Wired at the HTTP entry points:
+
+- API routes — `apiBuilder.server.ts` wraps each handler invocation in `tenantContext.run` using the authenticated `environment`.
+- Dashboard requests — an Express middleware (`tenantContextMiddleware`) resolves org/project/env from the URL pattern `/orgs/:org/projects/:project/env/:env/...` and wraps the Remix handler.
+
+Background workers (redis-worker / schedule-engine) and socket handlers are not yet wired and remain a follow-up. Events from those entry points will continue to ship without tenant attribution until each handler is updated.

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";
@@ -289,9 +291,14 @@ process.on("uncaughtException", (error, origin) => {
 singleton("RunEngineEventBusHandlers", registerRunEngineEventBusHandlers);
 singleton("SetupBatchQueueCallbacks", setupBatchQueueCallbacks);
 
+if (process.env.SENTRY_DSN) {
+  Sentry.addEventProcessor(addTenantContextToEvent);
+}
+
 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/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 {
@@ -903,15 +911,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 {

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

@@ -0,0 +1,32 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { AuthenticatedEnvironment } from "./apiAuth.server";
+
+export type TenantContext = {
+  org: { id: string; slug: string };
+  project: { id: string; ref: string };
+  environment: {
+    id: string;
+    slug: string;
+    type: "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();
+  },
+};
+
+export function tenantContextFromAuthEnvironment(env: AuthenticatedEnvironment): TenantContext {
+  return {
+    org: { id: env.organization.id, slug: env.organization.slug },
+    project: { id: env.project.id, ref: env.project.externalRef },
+    environment: { id: env.id, slug: env.slug, type: env.type },
+  };
+}

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

@@ -0,0 +1,78 @@
+import type { NextFunction, Request, Response } from "express";
+import { prisma } from "~/db.server";
+import { tenantContext, type TenantContext } from "./tenantContext.server";
+import { logger } from "./logger.server";
+
+const URL_PATTERN = /^\/orgs\/([^/]+)(?:\/projects\/([^/]+)(?:\/env\/([^/]+))?)?/;
+
+export type ParsedTenantPath = {
+  orgSlug: string;
+  projectParam: string;
+  envParam: string;
+};
+
+export function parseTenantPath(pathname: string): ParsedTenantPath | undefined {
+  const match = pathname.match(URL_PATTERN);
+  if (!match) return undefined;
+  const [, orgSlug, projectParam, envParam] = match;
+  if (!orgSlug || !projectParam || !envParam) return undefined;
+  return { orgSlug, projectParam, envParam };
+}
+
+export async function resolveTenantContextFromPath(
+  pathname: string
+): Promise<TenantContext | undefined> {
+  const parsed = parseTenantPath(pathname);
+  if (!parsed) return undefined;
+
+  try {
+    const env = await prisma.runtimeEnvironment.findFirst({
+      where: {
+        slug: parsed.envParam,
+        project: { slug: parsed.projectParam, organization: { slug: parsed.orgSlug } },
+      },
+      select: {
+        id: true,
+        slug: true,
+        type: true,
+        project: { select: { id: true, externalRef: true } },
+        organization: { select: { id: true, slug: true } },
+      },
+    });
+    if (!env) return undefined;
+    return {
+      org: { id: env.organization.id, slug: env.organization.slug },
+      project: { id: env.project.id, ref: env.project.externalRef },
+      environment: {
+        id: env.id,
+        slug: env.slug,
+        type: env.type,
+      },
+    };
+  } catch (error) {
+    logger.warn("tenantContextResolver: lookup failed", {
+      error: error instanceof Error ? error.message : String(error),
+      pathname,
+    });
+    return undefined;
+  }
+}
+
+export type PathResolver = (pathname: string) => Promise<TenantContext | undefined>;
+
+export function createTenantContextMiddleware(resolver: PathResolver) {
+  return async function tenantContextMiddleware(
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ) {
+    const ctx = await resolver(req.path);
+    if (ctx) {
+      tenantContext.run(ctx, () => next());
+    } else {
+      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,
+    user: {
+      ...event.user,
+      id: ctx.org.id,
+      username: ctx.org.slug,
+    },
+    tags: {
+      ...event.tags,
+      org_id: ctx.org.id,
+      org_slug: ctx.org.slug,
+      project_id: ctx.project.id,
+      project_ref: ctx.project.ref,
+      environment_id: ctx.environment.id,
+      env_slug: ctx.environment.slug,
+      env_type: ctx.environment.type,
+      ...(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

apps/webapp/test/sentryTenantContext.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import type { Event } from "@sentry/remix";
+import { tenantContext } from "../app/services/tenantContext.server";
+import { addTenantContextToEvent } from "../app/utils/sentryTenantContext.server";
+
+const sample = {
+  org: { id: "org_1", slug: "acme" },
+  project: { id: "proj_1", ref: "proj_abc" },
+  environment: { id: "env_1", slug: "prod", type: "PRODUCTION" as const },
+};
+
+describe("addTenantContextToEvent", () => {
+  it("returns the event unchanged when no ALS context", () => {
+    const event: Event = { message: "hi", tags: { existing: "1" } };
+    const out = addTenantContextToEvent(event, {});
+    expect(out).toEqual(event);
+  });
+
+  it("stamps user + tags when ALS context is set", () => {
+    tenantContext.run(sample, () => {
+      const event: Event = { message: "boom", tags: { existing: "1" } };
+      const out = addTenantContextToEvent(event, {});
+      expect(out.user).toEqual({ id: "org_1", username: "acme" });
+      expect(out.tags).toMatchObject({
+        existing: "1",
+        org_id: "org_1",
+        org_slug: "acme",
+        project_id: "proj_1",
+        project_ref: "proj_abc",
+        environment_id: "env_1",
+        env_slug: "prod",
+        env_type: "PRODUCTION",
+      });
+      expect(out.tags?.impersonating).toBeUndefined();
+    });
+  });
+
+  it("adds impersonating tag when flag set", () => {
+    tenantContext.run({ ...sample, impersonating: true }, () => {
+      const out = addTenantContextToEvent({}, {});
+      expect(out.tags?.impersonating).toBe("true");
+    });
+  });
+
+  it("preserves prior event.user fields it does not own", () => {
+    tenantContext.run(sample, () => {
+      const event: Event = { user: { ip_address: "1.2.3.4" } };
+      const out = addTenantContextToEvent(event, {});
+      expect(out.user).toEqual({ ip_address: "1.2.3.4", id: "org_1", username: "acme" });
+    });
+  });
+});

apps/webapp/test/tenantContext.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { tenantContext, type TenantContext } from "../app/services/tenantContext.server";
+
+const sample: TenantContext = {
+  org: { id: "org_1", slug: "acme" },
+  project: { id: "proj_1", ref: "proj_abc" },
+  environment: { id: "env_1", slug: "prod", type: "PRODUCTION" },
+};
+
+describe("tenantContext", () => {
+  it("returns undefined outside run()", () => {
+    expect(tenantContext.get()).toBeUndefined();
+  });
+
+  it("returns the active context inside run()", () => {
+    tenantContext.run(sample, () => {
+      expect(tenantContext.get()).toEqual(sample);
+    });
+  });
+
+  it("isolates concurrent async trees", async () => {
+    const a: TenantContext = { ...sample, org: { id: "org_a", slug: "a" } };
+    const b: TenantContext = { ...sample, org: { id: "org_b", slug: "b" } };
+
+    const [got1, got2] = await Promise.all([
+      tenantContext.run(a, async () => {
+        await new Promise((r) => setTimeout(r, 10));
+        return tenantContext.get()?.org.id;
+      }),
+      tenantContext.run(b, async () => {
+        await new Promise((r) => setTimeout(r, 5));
+        return tenantContext.get()?.org.id;
+      }),
+    ]);
+    expect(got1).toBe("org_a");
+    expect(got2).toBe("org_b");
+  });
+
+  it("supports nested run() overriding", () => {
+    const inner: TenantContext = { ...sample, org: { id: "org_inner", slug: "inner" } };
+    tenantContext.run(sample, () => {
+      tenantContext.run(inner, () => {
+        expect(tenantContext.get()?.org.id).toBe("org_inner");
+      });
+      expect(tenantContext.get()?.org.id).toBe("org_1");
+    });
+  });
+});