🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(audit-logs): stage change events next to the Postgres audit log (#18769)
Steffen Reutherc2af0e6e3731
diff --git a/.env.prod.example b/.env.prod.exampleindex af35519fe5..a9bb5a6c4d 100644--- a/.env.prod.example+++ b/.env.prod.example@@ -444,6 +444,11 @@ LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG=true# NEXT_PUBLIC_LANGFUSE_CLOUD_REGION="US"# NEXTAUTH_COOKIE_DOMAIN=".langfuse.com"+# Stages each audit event for ClickHouse next to its Postgres audit_logs row.+# Runs only when the cloud region above is set. Set to false to stop staging;+# the Postgres row is written either way.+# LANGFUSE_AUDIT_LOG_STAGING_ENABLED=true+# Moves staged audit events from Postgres into ClickHouse. Runs only when the# cloud region above is set. While it is disabled, staged events wait in# Postgres.diff --git a/packages/shared/src/server/repositories/auditLogs.ts b/packages/shared/src/server/repositories/auditLogs.tsindex fa7dca67fb..e4655e9fed 100644--- a/packages/shared/src/server/repositories/auditLogs.ts+++ b/packages/shared/src/server/repositories/auditLogs.ts@@ -1,3 +1,4 @@+import { createHash } from "node:crypto";import { v7 as uuidv7 } from "uuid";import { prisma, type AuditLogStaging, type Prisma } from "../../db";import {@@ -43,6 +44,43 @@ export async function stageAuditLogEvents(return rows.map((row) => row.id);}+/**+ * The audit event id of a row in the Postgres `audit_logs` table, whose own+ * id is a cuid. It is a UUIDv7 that carries the row's `created_at` as its+ * timestamp and the first bits of a SHA-256 of the cuid as its random bits.+ * The same row therefore always maps to the same id, so the ClickHouse+ * `audit_logs` table collapses its copies.+ */+export function deriveAuditLogEventId(+ auditLogId: string,+ createdAt: Date,+): string {+ const timestampMs = createdAt.getTime();+ if (+ !Number.isInteger(timestampMs) ||+ timestampMs < 0 ||+ timestampMs >= 2 ** 48+ ) {+ throw new Error(`Audit log ${auditLogId} has an invalid created_at`);+ }++ const bytes = createHash("sha256").update(auditLogId).digest();+ bytes.writeUIntBE(timestampMs, 0, 6);+ // Version 7 in the high nibble of byte 6, the RFC 9562 variant (0b10) in+ // the top two bits of byte 8.+ bytes[6] = 0x70 + (bytes[6] % 0x10);+ bytes[8] = 0x80 + (bytes[8] % 0x40);++ const hex = bytes.subarray(0, 16).toString("hex");+ return [+ hex.slice(0, 8),+ hex.slice(8, 12),+ hex.slice(12, 16),+ hex.slice(16, 20),+ hex.slice(20, 32),+ ].join("-");+}+/*** Maps a staging row to its ClickHouse `audit_logs` row. The staging row's* `created_at` is the event timestamp. Throws when the payload does notdiff --git a/web/src/__tests__/server/audit-log-license-gate.servertest.ts b/web/src/__tests__/server/audit-log-license-gate.servertest.tsindex 00dcacbe9b..6a2924ca21 100644--- a/web/src/__tests__/server/audit-log-license-gate.servertest.ts+++ b/web/src/__tests__/server/audit-log-license-gate.servertest.ts@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";const mocks = vi.hoisted(() => ({cloudRegion: undefined as string | undefined,licenseKey: undefined as string | undefined,+ stagingEnabled: "true",}));// Exercise the real gate rather than mocking it away: spread the real env and@@ -18,6 +19,8 @@ vi.mock("@/src/env.mjs", async (importOriginal) => {if (prop === "NEXT_PUBLIC_LANGFUSE_CLOUD_REGION")return mocks.cloudRegion;if (prop === "LANGFUSE_EE_LICENSE_KEY") return mocks.licenseKey;+ if (prop === "LANGFUSE_AUDIT_LOG_STAGING_ENABLED")+ return mocks.stagingEnabled;return Reflect.get(target, prop);},}),@@ -27,13 +30,18 @@ vi.mock("@/src/env.mjs", async (importOriginal) => {import { auditLog } from "@/src/features/audit-logs/server";import { prisma } from "@langfuse/shared/src/db";import { createApiKey } from "@langfuse/shared/src/server/auth/apiKeys";-import { createOrgProjectAndApiKey, logger } from "@langfuse/shared/src/server";+import {+ createOrgProjectAndApiKey,+ deriveAuditLogEventId,+ logger,+} from "@langfuse/shared/src/server";import { ProjectId, SystemRoleId } from "@langfuse/shared/rbac";/*** Audit log records are an enterprise feature, so they are only persisted when- * the instance is licensed for them. The actor log line that mirrors each- * record is operator telemetry and stays on every plan.+ * the instance is licensed for them. They are staged for ClickHouse on Cloud+ * only, where the relay runs. The actor log line that mirrors each record is+ * operator telemetry and stays on every plan.*/describe("audit log license gate", () => {let orgId: string;@@ -44,6 +52,7 @@ describe("audit log license gate", () => {beforeEach(async () => {mocks.cloudRegion = undefined;mocks.licenseKey = undefined;+ mocks.stagingEnabled = "true";const org = await createOrgProjectAndApiKey();orgId = org.orgId;@@ -62,7 +71,7 @@ describe("audit log license gate", () => {vi.restoreAllMocks();});- /** Writes one record per actor shape, returns how many were persisted. */+ /** Writes one record per actor shape, counts the persisted and staged ones. */const auditAllActorShapes = async () => {const resourceIds = [randomUUID(), randomUUID(), randomUUID()];@@ -89,20 +98,29 @@ describe("audit log license gate", () => {projectId,});- return prisma.auditLog.count({+ const records = await prisma.auditLog.findMany({where: { resourceId: { in: resourceIds } },+ select: { id: true, createdAt: true },});+ const stagedIds = records.map((record) =>+ deriveAuditLogEventId(record.id, record.createdAt),+ );+ const staged = await prisma.auditLogStaging.deleteMany({+ where: { id: { in: stagedIds } },+ });++ return { persisted: records.length, staged: staged.count };};describe("self-hosted", () => {- it("persists records with an enterprise license key", async () => {+ it("persists records with an enterprise license key, without staging them", async () => {mocks.licenseKey = "langfuse_ee_test";- expect(await auditAllActorShapes()).toBe(3);+ expect(await auditAllActorShapes()).toEqual({ persisted: 3, staged: 0 });});it("persists no records without a license key", async () => {- expect(await auditAllActorShapes()).toBe(0);+ expect(await auditAllActorShapes()).toEqual({ persisted: 0, staged: 0 });});it("persists no records on a pro license key", async () => {@@ -110,15 +128,22 @@ describe("audit log license gate", () => {// not persist records it cannot view either.mocks.licenseKey = "langfuse_pro_test";- expect(await auditAllActorShapes()).toBe(0);+ expect(await auditAllActorShapes()).toEqual({ persisted: 0, staged: 0 });});});describe("cloud", () => {- it("persists records on every plan", async () => {+ it("persists and stages records on every plan", async () => {+ mocks.cloudRegion = "US";++ expect(await auditAllActorShapes()).toEqual({ persisted: 3, staged: 3 });+ });++ it("persists records without staging them when staging is switched off", async () => {mocks.cloudRegion = "US";+ mocks.stagingEnabled = "false";- expect(await auditAllActorShapes()).toBe(3);+ expect(await auditAllActorShapes()).toEqual({ persisted: 3, staged: 0 });});});@@ -128,7 +153,7 @@ describe("audit log license gate", () => {// mutations that have no parallel logger call of their own.const info = vi.spyOn(logger, "info");- expect(await auditAllActorShapes()).toBe(0);+ expect((await auditAllActorShapes()).persisted).toBe(0);const actorLines = info.mock.calls.filter(([message]) =>String(message).startsWith("Audit log: job."),diff --git a/web/src/__tests__/server/audit-log-staging.servertest.ts b/web/src/__tests__/server/audit-log-staging.servertest.tsindex 3491ea2efe..eeae84f685 100644--- a/web/src/__tests__/server/audit-log-staging.servertest.ts+++ b/web/src/__tests__/server/audit-log-staging.servertest.ts@@ -1,13 +1,35 @@import { randomUUID } from "node:crypto";-import { afterAll, describe, expect, it } from "vitest";-import { toAuditLogResourceRef } from "@langfuse/shared";+import { version as uuidVersion, validate as isUuid } from "uuid";+import { afterAll, afterEach, describe, expect, it, vi } from "vitest";++// auditLog() stages its events on Cloud only.+vi.mock("@/src/env.mjs", async (importOriginal) => {+ const original = (await importOriginal()) as { env: Record<string, unknown> };+ return {+ ...original,+ env: new Proxy(original.env, {+ get: (target, prop) =>+ prop === "NEXT_PUBLIC_LANGFUSE_CLOUD_REGION"+ ? "US"+ : Reflect.get(target, prop),+ }),+ };+});++import { toAuditLogResourceRef, type AuditLogActor } from "@langfuse/shared";import { prisma } from "@langfuse/shared/src/db";+import { ProjectId, SystemRoleId, UserId } from "@langfuse/shared/rbac";import {clickhouseClient,convertAuditLogStagingRowToClickhouse,+ createOrgProjectAndApiKey,+ deriveAuditLogEventId,+ logger,stageAuditLogEvents,type AuditLogRecordInsertType,} from "@langfuse/shared/src/server";+import { createApiKey } from "@langfuse/shared/src/server/auth/apiKeys";+import { auditLog } from "@/src/features/audit-logs/server";const queryAuditLogs = async (query: string,@@ -229,4 +251,251 @@ describe("audit log staging", () => {}),).toThrow("actor.sessionId, dataSubject");});++ it("derives one time-ordered UUIDv7 per Postgres audit log row", () => {+ const createdAt = new Date("2026-10-14T09:30:00.123Z");+ const id = deriveAuditLogEventId("cm2abc0000000000000000001", createdAt);++ // Rows staged now and rows a later backfill copies from Postgres must get+ // the same id, so the derivation must never change.+ expect(id).toBe("01a139bf-4a3b-7791-9d80-a8821b47ea77");+ expect(isUuid(id) && uuidVersion(id)).toBe(7);+ expect(id.replaceAll("-", "").slice(0, 12)).toBe(+ createdAt.getTime().toString(16).padStart(12, "0"),+ );+ expect(deriveAuditLogEventId("cm2abc0000000000000000001", createdAt)).toBe(+ id,+ );+ expect(+ deriveAuditLogEventId("cm2abc0000000000000000002", createdAt),+ ).not.toBe(id);+ expect(+ deriveAuditLogEventId(+ "cm2abc0000000000000000001",+ new Date(createdAt.getTime() + 1),+ ) > id,+ ).toBe(true);+ });++ describe("auditLog shadow write", () => {+ afterEach(() => {+ vi.restoreAllMocks();+ });++ /** The Postgres row written for `resourceId` and the event staged for it. */+ const findRecordAndStagedEvent = async (resourceId: string) => {+ const record = await prisma.auditLog.findFirstOrThrow({+ where: { resourceId },+ });+ const id = deriveAuditLogEventId(record.id, record.createdAt);+ stagedIds.push(id);+ const staged = await prisma.auditLogStaging.findUniqueOrThrow({+ where: { id },+ });+ return { record, staged };+ };++ it("stages the change event of the Postgres row under the id derived from it", async () => {+ const { orgId, projectId } = await createOrgProjectAndApiKey();+ const resourceId = randomUUID();++ await auditLog({+ session: {+ user: {+ id: "user-1",+ name: "Ada Lovelace",+ email: "[email protected]",+ },+ orgId,+ orgRole: "ADMIN",+ projectId,+ projectRole: "MEMBER",+ },+ resourceType: "prompt",+ resourceId,+ action: "update",+ before: { version: 1 },+ after: { version: 2 },+ });++ const { record, staged } = await findRecordAndStagedEvent(resourceId);+ expect(staged.createdAt).toEqual(record.createdAt);+ expect(record).toMatchObject({+ before: '{"version":1}',+ after: '{"version":2}',+ });+ expect(convertAuditLogStagingRowToClickhouse(staged)).toMatchObject({+ event_kind: "change",+ org_id: orgId,+ project_id: projectId,+ actor_type: "USER",+ user_id: "user-1",+ actor_name: "Ada Lovelace",+ actor_email: "[email protected]",+ user_org_role: "ADMIN",+ user_project_role: "MEMBER",+ resource_type: "prompt",+ resource_id: resourceId,+ action: "update",+ before: record.before,+ after: record.after,+ });+ });++ it("stages SYSTEM, API key and in-app agent actors", async () => {+ const { orgId, projectId, publicKey } = await createOrgProjectAndApiKey();+ const { id: projectApiKeyId } = await prisma.apiKey.findUniqueOrThrow({+ where: { publicKey },+ select: { id: true },+ });+ const creator = await prisma.user.create({+ data: { email: `${randomUUID()}@test.com`, name: "Agent Owner" },+ });+ const agentKey = await createApiKey(prisma, {+ owner: ProjectId(projectId),+ role: SystemRoleId("LEGACY_PROJECT_API_KEY"),+ createdBy: UserId(creator.id),+ name: "In-app agent MCP session",+ isInAppAgentKey: true,+ });++ // Per actor: what the Postgres row keeps, and the actor staged for it.+ const cases: {+ actor:+ | { session: { user: { id: string }; orgId: string } }+ | { apiKeyId: string; orgId: string };+ record: { userId: string | null; apiKeyId: string | null };+ staged: AuditLogActor;+ }[] = [+ {+ actor: { session: { user: { id: "stripe-webhook" }, orgId } },+ record: { userId: "stripe-webhook", apiKeyId: null },+ staged: { type: "SYSTEM", name: "stripe-webhook" },+ },+ {+ actor: { apiKeyId: "ADMIN_KEY", orgId },+ record: { userId: null, apiKeyId: "ADMIN_KEY" },+ staged: { type: "SYSTEM", name: "admin-api" },+ },+ {+ actor: { apiKeyId: "ADMIN_API_KEY", orgId },+ record: { userId: null, apiKeyId: "ADMIN_API_KEY" },+ staged: { type: "SYSTEM", name: "admin-api" },+ },+ {+ actor: { apiKeyId: projectApiKeyId, orgId },+ record: { userId: null, apiKeyId: projectApiKeyId },+ staged: { type: "API_KEY", apiKeyId: projectApiKeyId },+ },+ {+ actor: { apiKeyId: agentKey.id, orgId },+ record: { userId: creator.id, apiKeyId: agentKey.id },+ staged: {+ type: "API_KEY",+ apiKeyId: agentKey.id,+ userId: creator.id,+ name: "Agent Owner",+ email: creator.email!,+ },+ },+ ];++ for (const { actor, ...expected } of cases) {+ const resourceId = randomUUID();+ await auditLog({+ ...actor,+ resourceType: "job",+ resourceId,+ action: "create",+ });++ const { record, staged } = await findRecordAndStagedEvent(resourceId);+ expect(record).toMatchObject(expected.record);+ expect((staged.payload as { actor: unknown }).actor).toEqual(+ expected.staged,+ );+ }+ });++ it("logs a failed staging insert without failing the caller", async () => {+ const { orgId } = await createOrgProjectAndApiKey();+ const resourceId = randomUUID();+ vi.spyOn(prisma.auditLogStaging, "createMany").mockRejectedValueOnce(+ new Error("staging unavailable"),+ );+ const error = vi.spyOn(logger, "error");++ await auditLog({+ session: { user: { id: "user-1" }, orgId },+ resourceType: "prompt",+ resourceId,+ action: "delete",+ });++ expect(error).toHaveBeenCalledWith(+ "Failed to stage audit log event",+ expect.objectContaining({ resourceId }),+ );+ expect(await prisma.auditLog.count({ where: { resourceId } })).toBe(1);+ });++ it("keeps the caller's transaction usable when the staging insert fails in it", async () => {+ const { orgId } = await createOrgProjectAndApiKey();+ const resourceId = randomUUID();+ const error = vi.spyOn(logger, "error");++ await prisma.$transaction(async (tx) => {+ // Fails the way a rejected insert does: Postgres aborts the+ // transaction.+ const stagingInsert = vi+ .spyOn(tx.auditLogStaging, "createMany")+ .mockImplementationOnce(() => tx.$queryRaw`SELECT 1 / 0`);++ await auditLog(+ {+ session: { user: { id: "user-1" }, orgId },+ resourceType: "prompt",+ resourceId,+ action: "delete",+ },+ tx,+ );++ expect(stagingInsert).toHaveBeenCalledOnce();+ expect(await tx.auditLog.count({ where: { resourceId } })).toBe(1);+ });++ expect(error).toHaveBeenCalledWith(+ "Failed to stage audit log event",+ expect.objectContaining({ resourceId }),+ );+ expect(await prisma.auditLog.count({ where: { resourceId } })).toBe(1);+ });++ it("stages nothing when the caller's transaction rolls back", async () => {+ const { orgId } = await createOrgProjectAndApiKey();+ const resourceId = randomUUID();++ await expect(+ prisma.$transaction(async (tx) => {+ await auditLog(+ {+ session: { user: { id: "user-1" }, orgId },+ resourceType: "prompt",+ resourceId,+ action: "delete",+ },+ tx,+ );+ throw new Error("audited mutation failed");+ }),+ ).rejects.toThrow("audited mutation failed");++ expect(+ await prisma.auditLogStaging.count({+ where: { payload: { path: ["resourceId"], equals: resourceId } },+ }),+ ).toBe(0);+ });+ });});diff --git a/web/src/env.mjs b/web/src/env.mjsindex 562ce08fa8..5fe15ac433 100644--- a/web/src/env.mjs+++ b/web/src/env.mjs@@ -687,6 +687,12 @@ export const env = createEnv({.nonnegative().default(0),+ // Kill switch for staging audit events for the ClickHouse audit_logs table+ // on Langfuse Cloud. The Postgres audit_logs row is written either way.+ LANGFUSE_AUDIT_LOG_STAGING_ENABLED: z+ .enum(["true", "false"])+ .default("true"),+// Background-migration env gates. Mirror worker/src/env.ts (names, defaults)// so the background-migrations status endpoint can tell dormant, env-gated// rows apart from migrations the worker will actually pick up. The worker@@ -1265,6 +1271,8 @@ export const env = createEnv({LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT:process.env.LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT,LANGFUSE_TRUSTED_PROXY_COUNT: process.env.LANGFUSE_TRUSTED_PROXY_COUNT,+ LANGFUSE_AUDIT_LOG_STAGING_ENABLED:+ process.env.LANGFUSE_AUDIT_LOG_STAGING_ENABLED,LANGFUSE_BACKGROUND_MIGRATION_V4_ENABLE_HISTORIC_BACKFILL:process.env.LANGFUSE_BACKGROUND_MIGRATION_V4_ENABLE_HISTORIC_BACKFILL,LANGFUSE_BACKGROUND_MIGRATION_V4_DROP_PID_TID_SORTING_TABLES:diff --git a/web/src/features/audit-logs/auditLog.ts b/web/src/features/audit-logs/auditLog.tsindex 12c4c7aa86..867f5ba494 100644--- a/web/src/features/audit-logs/auditLog.ts+++ b/web/src/features/audit-logs/auditLog.ts@@ -4,10 +4,16 @@ import {AuditLogRecordType,type Prisma,} from "@langfuse/shared/src/db";+import { type AuditLogActor as StagedAuditLogActor } from "@langfuse/shared";import {+ deriveAuditLogEventId,formatSubmittedPublicKeyForLog,logger,+ recordIncrement,+ stageAuditLogEvents,+ type StageAuditLogEventInput,} from "@langfuse/shared/src/server";+import { env } from "@/src/env.mjs";import { isAuditLogEnabled } from "@/src/features/audit-logs/isAuditLogEnabled";type AuditableResource =@@ -74,6 +80,8 @@ export type AuditLogActor =session: {user: {id: string;+ name?: string | null;+ email?: string | null;};orgId: string;orgRole?: Role;@@ -95,6 +103,21 @@ export type AuditLog = {after?: unknown;} & AuditLogActor;+// Writes made by Langfuse itself rather than by a user or an API key pass these+// sentinel actor ids. The Postgres row keeps them, because its actor type+// cannot be SYSTEM. The staged event records a SYSTEM actor instead.+const SYSTEM_ACTOR_USER_IDS = new Set(["stripe-webhook", "clickhouse-webhook"]);+const ADMIN_API_KEY_IDS = new Set(["ADMIN_KEY", "ADMIN_API_KEY"]);+const ADMIN_API_ACTOR: StagedAuditLogActor = {+ type: "SYSTEM",+ name: "admin-api",+};++const STAGED_RECORD_SELECT = {+ id: true,+ createdAt: true,+} satisfies Prisma.AuditLogSelect;+// Mirrors each audit log record into the application logs so that actors can be// correlated with web/worker log lines (e.g. trace deletions) without querying// the audit_logs table. Only ids are logged, no emails or names.@@ -144,6 +167,11 @@ export async function auditLog(// that have no parallel logger call of their own, and the actor logging added// alongside it elsewhere — batch actions, trace deletion — is ungated too.const persistRecord = isAuditLogEnabled();+ // Persisted records are also staged for ClickHouse, on Cloud only: the+ // worker relay that drains the staging table runs only there.+ const stageRecord =+ Boolean(env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION) &&+ env.LANGFUSE_AUDIT_LOG_STAGING_ENABLED === "true";const db = prisma ?? _prisma;// Defer JSON.stringify(before/after) until we know the record will be@@ -168,6 +196,10 @@ export async function auditLog(isInAppAgentKey: true,createdByUserId: true,publicKey: true,+ // The staged event names the user an in-app agent key acts for.+ createdByUser: stageRecord+ ? { select: { name: true, email: true } }+ : false,},});@@ -188,7 +220,7 @@ export async function auditLog(if (!persistRecord) return;- await db.auditLog.create({+ const record = await db.auditLog.create({data: {apiKeyId: log.apiKeyId,userId,@@ -197,8 +229,23 @@ export async function auditLog(type: AuditLogRecordType.API_KEY,...makeShared(),},+ select: STAGED_RECORD_SELECT,});+ if (stageRecord) {+ await stageChangeEvent(+ log,+ record,+ { orgId: log.orgId, projectId: log.projectId },+ toApiKeyActor(+ log.apiKeyId,+ userId,+ userId ? apiKey?.createdByUser : undefined,+ ),+ db,+ );+ }+return;}@@ -213,7 +260,7 @@ export async function auditLog(if (!persistRecord) return;- await db.auditLog.create({+ const record = await db.auditLog.create({data: {userId: log.session.user.id,orgId: log.session.orgId,@@ -223,8 +270,19 @@ export async function auditLog(type: AuditLogRecordType.USER,...makeShared(),},+ select: STAGED_RECORD_SELECT,});+ if (stageRecord) {+ await stageChangeEvent(+ log,+ record,+ { orgId: log.session.orgId, projectId: log.session.projectId },+ toUserActor(log.session.user, log.session),+ db,+ );+ }+return;}@@ -239,7 +297,7 @@ export async function auditLog(if (!persistRecord) return;- await db.auditLog.create({+ const record = await db.auditLog.create({data: {userId: log.userId,orgId: log.orgId,@@ -249,8 +307,121 @@ export async function auditLog(type: AuditLogRecordType.USER,...makeShared(),},+ select: STAGED_RECORD_SELECT,});+ if (stageRecord) {+ await stageChangeEvent(+ log,+ record,+ { orgId: log.orgId, projectId: log.projectId },+ toUserActor({ id: log.userId }, log),+ db,+ );+ }+return;}}++function toUserActor(+ user: { id: string; name?: string | null; email?: string | null },+ roles: { orgRole?: Role; projectRole?: Role },+): StagedAuditLogActor {+ if (SYSTEM_ACTOR_USER_IDS.has(user.id)) {+ return { type: "SYSTEM", name: user.id };+ }+ return {+ type: "USER",+ userId: user.id,+ name: user.name ?? undefined,+ email: user.email ?? undefined,+ orgRole: roles.orgRole,+ projectRole: roles.projectRole,+ };+}++/** `creator` is the user an in-app agent key acts for. */+function toApiKeyActor(+ apiKeyId: string,+ userId: string | undefined,+ creator: { name?: string | null; email?: string | null } | null | undefined,+): StagedAuditLogActor {+ if (ADMIN_API_KEY_IDS.has(apiKeyId)) return ADMIN_API_ACTOR;+ return {+ type: "API_KEY",+ apiKeyId,+ userId,+ name: creator?.name ?? undefined,+ email: creator?.email ?? undefined,+ };+}++/**+ * Stages the change event of a Postgres `audit_logs` row for the ClickHouse+ * `audit_logs` table, under the id `deriveAuditLogEventId` gives that row.+ * The Postgres row stays the source of truth, so a failure here is logged and+ * counted and never fails the caller. Given a transaction client, it stages+ * on that transaction.+ */+async function stageChangeEvent(+ log: AuditLog,+ record: { id: string; createdAt: Date },+ scope: { orgId: string; projectId?: string },+ actor: StagedAuditLogActor,+ db: typeof _prisma | Prisma.TransactionClient,+) {+ try {+ const event: StageAuditLogEventInput = {+ id: deriveAuditLogEventId(record.id, record.createdAt),+ timestamp: record.createdAt,+ kind: "change",+ orgId: scope.orgId,+ projectId: scope.projectId,+ actor,+ resourceType: log.resourceType,+ resourceId: log.resourceId,+ action: log.action,+ // Staging serializes these itself. Falsy values are dropped, as in the+ // Postgres row.+ before: log.before || undefined,+ after: log.after || undefined,+ };+ // Only the base client has $transaction.+ if ("$transaction" in db) {+ await stageAuditLogEvents([event], db);+ } else {+ await stageInSavepoint(event, db);+ }+ } catch (error) {+ recordIncrement("langfuse.audit_log.staging_write_failed");+ logger.error("Failed to stage audit log event", {+ error,+ resourceType: log.resourceType,+ resourceId: log.resourceId,+ action: log.action,+ orgId: scope.orgId,+ });+ }+}++/**+ * Stages the event on the caller's transaction, so it commits or rolls back+ * with the audited mutation and holds no second connection. A failed insert+ * aborts a Postgres transaction, so the insert runs behind a savepoint that a+ * failure rolls back to, which leaves the caller's transaction usable. Calls+ * on one transaction must not overlap, because they share the savepoint name.+ */+async function stageInSavepoint(+ event: StageAuditLogEventInput,+ tx: Prisma.TransactionClient,+) {+ await tx.$executeRaw`SAVEPOINT audit_log_staging`;+ try {+ await stageAuditLogEvents([event], tx);+ } catch (error) {+ await tx.$executeRaw`ROLLBACK TO SAVEPOINT audit_log_staging`;+ throw error;+ }+ await tx.$executeRaw`RELEASE SAVEPOINT audit_log_staging`;+}