Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(audit-logs): stage change events next to the Postgres audit log (#18769)

Steffen Reutherc2af0e6e3731
diff --git a/.env.prod.example b/.env.prod.example
index 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.ts
index 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 not
diff --git a/web/src/__tests__/server/audit-log-license-gate.servertest.ts b/web/src/__tests__/server/audit-log-license-gate.servertest.ts
index 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.ts
index 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.mjs
index 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.ts
index 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`;
+}