Skip to content

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

feat(audit-logs): add audit_logs table, staging outbox and event contract (#18671)

Steffen Reuthere3d264c38ec7
diff --git a/.env.prod.example b/.env.prod.example
index e76247f613..b7b29962c7 100644
--- a/.env.prod.example
+++ b/.env.prod.example
@@ -46,6 +46,11 @@ ENCRYPTION_KEY="0000000000000000000000000000000000000000000000000000000000000000
# Works at runtime with the pre-built docker image.
# LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT=150000
+# Number of reverse proxies in front of the web container that append to
+# X-Forwarded-For, optional. Used to record the client IP on audit log events.
+# 0 (default) ignores X-Forwarded-For and records the direct peer address.
+# LANGFUSE_TRUSTED_PROXY_COUNT=0
+
# Docker only, optional
# PORT=3000
# HOSTNAME=localhost
diff --git a/docker-compose.build.yml b/docker-compose.build.yml
index c0f219583a..e52865a496 100644
--- a/docker-compose.build.yml
+++ b/docker-compose.build.yml
@@ -36,6 +36,7 @@ services:
LANGFUSE_INIT_USER_NAME: ${LANGFUSE_INIT_USER_NAME:-}
LANGFUSE_INIT_USER_PASSWORD: ${LANGFUSE_INIT_USER_PASSWORD:-}
LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT: ${LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT:-}
+ LANGFUSE_TRUSTED_PROXY_COUNT: ${LANGFUSE_TRUSTED_PROXY_COUNT:-}
CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
diff --git a/docker-compose.yml b/docker-compose.yml
index 090a4e2f7d..2c545ba6f5 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -129,6 +129,7 @@ services:
LANGFUSE_INIT_USER_NAME: ${LANGFUSE_INIT_USER_NAME:-}
LANGFUSE_INIT_USER_PASSWORD: ${LANGFUSE_INIT_USER_PASSWORD:-}
LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT: ${LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT:-}
+ LANGFUSE_TRUSTED_PROXY_COUNT: ${LANGFUSE_TRUSTED_PROXY_COUNT:-}
# Hostnames allowed to reach the MCP endpoint, beyond NEXTAUTH_URL's own
# host. Required when the worker uses LANGFUSE_MCP_BASE_URL.
LANGFUSE_MCP_ALLOWED_HOSTS: ${LANGFUSE_MCP_ALLOWED_HOSTS:-}
diff --git a/packages/shared/clickhouse/migrations/canonical/0052_create_audit_logs.down.sql b/packages/shared/clickhouse/migrations/canonical/0052_create_audit_logs.down.sql
new file mode 100644
index 0000000000..419b967431
--- /dev/null
+++ b/packages/shared/clickhouse/migrations/canonical/0052_create_audit_logs.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS audit_logs {CLICKHOUSE_CLUSTER_CLAUSE};
diff --git a/packages/shared/clickhouse/migrations/canonical/0052_create_audit_logs.up.sql b/packages/shared/clickhouse/migrations/canonical/0052_create_audit_logs.up.sql
new file mode 100644
index 0000000000..afd63faadc
--- /dev/null
+++ b/packages/shared/clickhouse/migrations/canonical/0052_create_audit_logs.up.sql
@@ -0,0 +1,46 @@
+-- Audit log rows for change events (create, update, delete) and access events
+-- (single reads, lists, exports, downloads). Rows are append-only.
+-- ReplacingMergeTree collapses a row that is inserted twice, which is why `id`
+-- ends the sorting key. `project_id = ''` marks organisation-level events.
+-- `resource_refs` holds typed refs such as 'trace:<id>', so that
+-- has(resource_refs, 'trace:<id>') finds every event that touched a resource.
+CREATE TABLE IF NOT EXISTS audit_logs {CLICKHOUSE_CLUSTER_CLAUSE}
+(
+ id String,
+ timestamp DateTime64(3),
+ org_id String,
+ project_id String DEFAULT '',
+ event_kind LowCardinality(String),
+ outcome LowCardinality(String) DEFAULT 'success',
+ outcome_reason String DEFAULT '',
+ actor_type LowCardinality(String),
+ user_id String DEFAULT '',
+ api_key_id String DEFAULT '',
+ actor_name String DEFAULT '',
+ actor_email String DEFAULT '',
+ user_org_role LowCardinality(String) DEFAULT '',
+ user_project_role LowCardinality(String) DEFAULT '',
+ resource_type LowCardinality(String),
+ resource_id String DEFAULT '',
+ resource_refs Array(String) DEFAULT [],
+ action LowCardinality(String),
+ surface LowCardinality(String) DEFAULT '',
+ route String DEFAULT '',
+ params String DEFAULT '' CODEC(ZSTD(3)),
+ result_count UInt32 DEFAULT 0,
+ before String DEFAULT '' CODEC(ZSTD(3)),
+ after String DEFAULT '' CODEC(ZSTD(3)),
+ ip String DEFAULT '',
+ user_agent String DEFAULT '',
+ request_id String DEFAULT '',
+ inserted_at DateTime64(3) DEFAULT now64(3),
+
+ INDEX idx_resource_id resource_id TYPE bloom_filter(0.01) GRANULARITY 1,
+ INDEX idx_resource_refs resource_refs TYPE bloom_filter(0.01) GRANULARITY 1,
+ INDEX idx_user_id user_id TYPE bloom_filter(0.01) GRANULARITY 1,
+ INDEX idx_api_key_id api_key_id TYPE bloom_filter(0.01) GRANULARITY 1
+)
+ENGINE = {CLICKHOUSE_REPLICATION_PREFIX}ReplacingMergeTree
+PARTITION BY toYYYYMM(timestamp)
+PRIMARY KEY (org_id, project_id, toStartOfMinute(timestamp))
+ORDER BY (org_id, project_id, toStartOfMinute(timestamp), id);
diff --git a/packages/shared/prisma/migrations/20261012155316_add_audit_log_staging/migration.sql b/packages/shared/prisma/migrations/20261012155316_add_audit_log_staging/migration.sql
new file mode 100644
index 0000000000..18943a3790
--- /dev/null
+++ b/packages/shared/prisma/migrations/20261012155316_add_audit_log_staging/migration.sql
@@ -0,0 +1,16 @@
+-- CreateTable
+CREATE TABLE "audit_log_staging" (
+ "id" UUID NOT NULL,
+ "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "payload" JSONB NOT NULL,
+
+ CONSTRAINT "audit_log_staging_pkey" PRIMARY KEY ("id")
+);
+
+-- Every row is deleted shortly after it is inserted. Vacuum after a fixed
+-- number of dead rows instead of a fraction of the table, so a backlog that
+-- inflates the row estimate does not postpone vacuuming once it drains.
+ALTER TABLE "audit_log_staging" SET (
+ autovacuum_vacuum_scale_factor = 0,
+ autovacuum_vacuum_threshold = 1000
+);
diff --git a/packages/shared/prisma/schema.prisma b/packages/shared/prisma/schema.prisma
index 03d5e99236..e79f8cbfb1 100644
--- a/packages/shared/prisma/schema.prisma
+++ b/packages/shared/prisma/schema.prisma
@@ -1086,6 +1086,17 @@ model AuditLog {
@@map("audit_logs")
}
+// Outbox for audit events on their way to the ClickHouse `audit_logs` table.
+// A row is deleted once ClickHouse has acknowledged its insert, so the table
+// stays near-empty. `payload` holds an `AuditLogStagingPayload`.
+model AuditLogStaging {
+ id String @id @db.Uuid // UUIDv7, so id order follows creation time
+ createdAt DateTime @default(now()) @map("created_at")
+ payload Json
+
+ @@map("audit_log_staging")
+}
+
model EvalTemplate {
id String @id @default(cuid())
createdAt DateTime @default(now()) @map("created_at")
diff --git a/packages/shared/src/domain/auditLogs.test.ts b/packages/shared/src/domain/auditLogs.test.ts
new file mode 100644
index 0000000000..f31e2904d1
--- /dev/null
+++ b/packages/shared/src/domain/auditLogs.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+ AUDIT_LOG_PARAMS_MAX_BYTES,
+ AUDIT_LOG_RESOURCE_REFS_MAX,
+ AUDIT_LOG_TRUNCATION_MARKER,
+ AuditLogEventSchema,
+ toAuditLogResourceRef,
+ type AuditLogEvent,
+} from "./auditLogs";
+
+const accessEvent = (
+ overrides: Partial<Extract<AuditLogEvent, { kind: "access" }>>,
+): AuditLogEvent => ({
+ kind: "access",
+ orgId: "org-1",
+ projectId: "project-1",
+ actor: { type: "USER", userId: "user-1" },
+ resourceType: "trace",
+ action: "list",
+ ...overrides,
+});
+
+const parseAccess = (overrides: Parameters<typeof accessEvent>[0]) => {
+ const payload = AuditLogEventSchema.parse(accessEvent(overrides));
+ if (payload.kind !== "access") throw new Error("expected an access event");
+ return payload;
+};
+
+describe("AuditLogEventSchema size caps", () => {
+ it("keeps params under the cap as serialized JSON", () => {
+ const params = { filter: [{ column: "name", value: "checkout" }] };
+
+ expect(parseAccess({ params }).params).toBe(JSON.stringify(params));
+ });
+
+ it.each([
+ { name: "ASCII", char: "a" },
+ { name: "3-byte characters", char: "€" },
+ { name: "surrogate pairs", char: "😀" },
+ ])("cuts params with $name to the byte cap", ({ char }) => {
+ const params = { searchQuery: char.repeat(AUDIT_LOG_PARAMS_MAX_BYTES) };
+
+ const capped = parseAccess({ params }).params ?? "";
+
+ expect(Buffer.byteLength(capped)).toBeLessThanOrEqual(
+ AUDIT_LOG_PARAMS_MAX_BYTES,
+ );
+ expect(Buffer.byteLength(capped)).toBeGreaterThan(
+ AUDIT_LOG_PARAMS_MAX_BYTES - 4,
+ );
+ expect(capped.endsWith(AUDIT_LOG_TRUNCATION_MARKER)).toBe(true);
+ expect(capped.isWellFormed()).toBe(true);
+ });
+
+ it("dedupes resource refs and caps their count", () => {
+ const refs = Array.from(
+ { length: AUDIT_LOG_RESOURCE_REFS_MAX + 10 },
+ (_, i) => toAuditLogResourceRef("observation", `obs-${i}`),
+ );
+ const trace = toAuditLogResourceRef("trace", "trace-1");
+
+ const { resourceRefs } = parseAccess({
+ resourceRefs: [trace, trace, ...refs],
+ });
+
+ expect(resourceRefs).toHaveLength(AUDIT_LOG_RESOURCE_REFS_MAX);
+ expect(resourceRefs.slice(0, 2)).toEqual([trace, refs[0]]);
+ });
+
+ it.each(["prompt:p-1", "trace:", "trace-1"])(
+ "rejects the malformed resource ref %s",
+ (ref) => {
+ expect(() =>
+ AuditLogEventSchema.parse(
+ accessEvent({ resourceRefs: [ref as `trace:${string}`] }),
+ ),
+ ).toThrow();
+ },
+ );
+});
diff --git a/packages/shared/src/domain/auditLogs.ts b/packages/shared/src/domain/auditLogs.ts
new file mode 100644
index 0000000000..98194e5007
--- /dev/null
+++ b/packages/shared/src/domain/auditLogs.ts
@@ -0,0 +1,224 @@
+import { z } from "zod";
+
+// Audit events are written to the Postgres `audit_log_staging` table and from
+// there into the ClickHouse `audit_logs` table. A `change` event records a
+// mutation with its before/after state. An `access` event records a read: the
+// request params, the number of returned rows, and typed refs to the
+// resources that were opened or returned.
+
+/** Upper bound for the serialized `params` of an access event, in UTF-8 bytes. */
+export const AUDIT_LOG_PARAMS_MAX_BYTES = 2048;
+
+/** Upper bound for `outcomeReason` and the User-Agent, in UTF-8 bytes. */
+export const AUDIT_LOG_TEXT_MAX_BYTES = 512;
+
+/**
+ * Upper bound for `resourceRefs` on one event: twice the largest list page
+ * (1000 rows on GET /api/public/v2/observations), so a list can carry an
+ * observation ref and a trace ref for every row it returned.
+ */
+export const AUDIT_LOG_RESOURCE_REFS_MAX = 2000;
+
+/** Ends a value that was cut to its byte limit. Cut `params` are no longer valid JSON. */
+export const AUDIT_LOG_TRUNCATION_MARKER = "...[truncated]";
+
+const AUDIT_LOG_RESOURCE_REF_TYPES = [
+ "trace",
+ "observation",
+ "score",
+ "session",
+] as const;
+export type AuditLogResourceRefType =
+ (typeof AUDIT_LOG_RESOURCE_REF_TYPES)[number];
+
+// The type prefix keeps user-supplied ids of different resource types apart.
+const AuditLogResourceRefSchema = z.templateLiteral([
+ z.enum(AUDIT_LOG_RESOURCE_REF_TYPES),
+ ":",
+ z.string().min(1),
+]);
+export type AuditLogResourceRef = z.infer<typeof AuditLogResourceRefSchema>;
+
+export const toAuditLogResourceRef = (
+ type: AuditLogResourceRefType,
+ id: string,
+): AuditLogResourceRef => `${type}:${id}`;
+
+const AuditLogActorSchema = z.discriminatedUnion("type", [
+ z.object({
+ type: z.literal("USER"),
+ userId: z.string().min(1),
+ // Name and email as of the event, so removed members stay identifiable.
+ name: z.string().optional(),
+ email: z.string().optional(),
+ orgRole: z.string().optional(),
+ projectRole: z.string().optional(),
+ }),
+ z.object({
+ type: z.literal("API_KEY"),
+ apiKeyId: z.string().min(1),
+ // Set when the key acts on behalf of a user, e.g. an in-app agent key.
+ userId: z.string().optional(),
+ name: z.string().optional(),
+ email: z.string().optional(),
+ }),
+ z.object({
+ type: z.literal("SYSTEM"),
+ // The acting component, e.g. "stripe-webhook".
+ name: z.string().min(1),
+ }),
+]);
+export type AuditLogActor = z.infer<typeof AuditLogActorSchema>;
+
+const AuditRequestContextSchema = z.object({
+ ip: z.string().optional(),
+ userAgent: z.string().optional(),
+ requestId: z.string().optional(),
+});
+export type AuditRequestContext = z.infer<typeof AuditRequestContextSchema>;
+
+const AuditLogOutcomeSchema = z.enum(["success", "denied", "error"]);
+
+// Bounded by the UInt32 `result_count` column in ClickHouse.
+const ResultCountSchema = z.number().int().nonnegative().max(4_294_967_295);
+
+const StagedEventBaseSchema = z.object({
+ orgId: z.string().min(1),
+ // Absent for organisation-level events.
+ projectId: z.string().optional(),
+ actor: AuditLogActorSchema,
+ resourceType: z.string().min(1),
+ // Absent for lists, which identify their rows through `resourceRefs`.
+ resourceId: z.string().optional(),
+ resourceRefs: z.array(AuditLogResourceRefSchema),
+ action: z.string().min(1),
+ outcome: AuditLogOutcomeSchema,
+ outcomeReason: z.string().optional(),
+ surface: z.enum(["trpc", "public-api", "mcp"]).optional(),
+ route: z.string().optional(),
+ request: AuditRequestContextSchema.optional(),
+});
+
+/** The `payload` of an `audit_log_staging` row. */
+export const AuditLogStagingPayloadSchema = z.discriminatedUnion("kind", [
+ StagedEventBaseSchema.extend({
+ kind: z.literal("change"),
+ // Serialized JSON.
+ before: z.string().optional(),
+ after: z.string().optional(),
+ }),
+ StagedEventBaseSchema.extend({
+ kind: z.literal("access"),
+ // Serialized JSON of the validated request input, at most
+ // AUDIT_LOG_PARAMS_MAX_BYTES.
+ params: z.string().optional(),
+ resultCount: ResultCountSchema.optional(),
+ }),
+]);
+export type AuditLogStagingPayload = z.infer<
+ typeof AuditLogStagingPayloadSchema
+>;
+
+const utf8ByteLength = (char: string): number => {
+ const codePoint = char.codePointAt(0) ?? 0;
+ if (codePoint <= 0x7f) return 1;
+ if (codePoint <= 0x7ff) return 2;
+ if (codePoint <= 0xffff) return 3;
+ return 4;
+};
+
+const MARKER_BYTES = Array.from(AUDIT_LOG_TRUNCATION_MARKER).reduce(
+ (sum, char) => sum + utf8ByteLength(char),
+ 0,
+);
+
+// Cuts on a code point boundary, so the result never holds a lone surrogate,
+// which Postgres rejects in jsonb.
+const truncateUtf8 = (value: string, maxBytes: number): string => {
+ let bytes = 0;
+ let index = 0;
+ let cutAt: number | undefined;
+ for (const char of value) {
+ bytes += utf8ByteLength(char);
+ if (cutAt === undefined && bytes > maxBytes - MARKER_BYTES) cutAt = index;
+ if (bytes > maxBytes) {
+ return value.slice(0, cutAt) + AUDIT_LOG_TRUNCATION_MARKER;
+ }
+ index += char.length;
+ }
+ return value;
+};
+
+const cappedText = z
+ .string()
+ .optional()
+ .transform((value) =>
+ value === undefined
+ ? undefined
+ : truncateUtf8(value, AUDIT_LOG_TEXT_MAX_BYTES),
+ );
+
+const serializedJson = z
+ .unknown()
+ .optional()
+ .transform((value) =>
+ value === undefined || value === null ? undefined : JSON.stringify(value),
+ );
+
+// Postgres jsonb cannot store NUL or an unpaired surrogate. Both become U+FFFD,
+// so an event whose ids carry one still stages instead of failing the request.
+// `before`, `after` and `params` are already escaped by JSON.stringify.
+const toJsonbSafeStrings = (value: unknown): unknown => {
+ if (typeof value === "string") {
+ return value.replaceAll("\u0000", "\uFFFD").toWellFormed();
+ }
+ if (Array.isArray(value)) return value.map(toJsonbSafeStrings);
+ if (typeof value === "object" && value !== null) {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, entry]) => [
+ key,
+ toJsonbSafeStrings(entry),
+ ]),
+ );
+ }
+ return value;
+};
+
+const EventBaseSchema = StagedEventBaseSchema.extend({
+ resourceRefs: z
+ .array(AuditLogResourceRefSchema)
+ .default([])
+ .transform((refs) =>
+ Array.from(new Set(refs)).slice(0, AUDIT_LOG_RESOURCE_REFS_MAX),
+ ),
+ outcome: AuditLogOutcomeSchema.default("success"),
+ outcomeReason: cappedText,
+ request: AuditRequestContextSchema.extend({
+ userAgent: cappedText,
+ }).optional(),
+});
+
+/**
+ * An audit event as callers record it. Parsing serializes `before`, `after`
+ * and `params` to JSON, applies the size caps above and makes every string
+ * storable in jsonb, which yields an `AuditLogStagingPayload`.
+ */
+export const AuditLogEventSchema = z
+ .discriminatedUnion("kind", [
+ EventBaseSchema.extend({
+ kind: z.literal("change"),
+ before: serializedJson,
+ after: serializedJson,
+ }),
+ EventBaseSchema.extend({
+ kind: z.literal("access"),
+ params: serializedJson.transform((json) =>
+ json === undefined
+ ? undefined
+ : truncateUtf8(json, AUDIT_LOG_PARAMS_MAX_BYTES),
+ ),
+ resultCount: ResultCountSchema.optional(),
+ }),
+ ])
+ .transform((event) => toJsonbSafeStrings(event) as typeof event);
+export type AuditLogEvent = z.input<typeof AuditLogEventSchema>;
diff --git a/packages/shared/src/domain/index.ts b/packages/shared/src/domain/index.ts
index 70d750bca1..245e31aada 100644
--- a/packages/shared/src/domain/index.ts
+++ b/packages/shared/src/domain/index.ts
@@ -9,3 +9,4 @@ export * from "./webhooks";
export * from "./prompts";
export * from "./dataset-items";
export * from "./media";
+export * from "./auditLogs";
diff --git a/packages/shared/src/server/clickhouse/schema.ts b/packages/shared/src/server/clickhouse/schema.ts
index b70a2a4b40..3c9a8e41ee 100644
--- a/packages/shared/src/server/clickhouse/schema.ts
+++ b/packages/shared/src/server/clickhouse/schema.ts
@@ -3,6 +3,7 @@ export const ClickhouseTableNames = {
observations: "observations",
scores: "scores",
dataset_run_items_rmt: "dataset_run_items_rmt",
+ audit_logs: "audit_logs",
// Virtual table for UI column mappings validation (eventsTableUiColumnDefinitions).
events_proto: "events_proto",
diff --git a/packages/shared/src/server/repositories/auditLogs.ts b/packages/shared/src/server/repositories/auditLogs.ts
new file mode 100644
index 0000000000..1545fe41f8
--- /dev/null
+++ b/packages/shared/src/server/repositories/auditLogs.ts
@@ -0,0 +1,86 @@
+import { v7 as uuidv7 } from "uuid";
+import { prisma, type AuditLogStaging, type Prisma } from "../../db";
+import {
+ AuditLogEventSchema,
+ AuditLogStagingPayloadSchema,
+ type AuditLogEvent,
+ type AuditLogStagingPayload,
+} from "../../domain/auditLogs";
+import { convertDateToClickhouseDateTime } from "../clickhouse/client";
+import type { AuditLogRecordInsertType } from "./definitions";
+
+export type StageAuditLogEventInput = AuditLogEvent & {
+ // A UUID. Defaults to a new UUIDv7. Pass one to give another record the
+ // same id.
+ id?: string;
+ // Defaults to now.
+ timestamp?: Date;
+};
+
+/**
+ * Writes audit events to `audit_log_staging` and returns their ids in input
+ * order. Throws when an event is invalid or the insert fails, so a caller
+ * that must not proceed without its audit row fails with it. Pass `tx` to
+ * commit the rows together with the audited mutation.
+ */
+export async function stageAuditLogEvents(
+ events: StageAuditLogEventInput[],
+ tx?: Prisma.TransactionClient,
+): Promise<string[]> {
+ if (events.length === 0) return [];
+
+ const rows = events.map(({ id, timestamp, ...event }) => {
+ const payload: AuditLogStagingPayload = AuditLogEventSchema.parse(event);
+ return {
+ id: id ?? uuidv7(),
+ createdAt: timestamp ?? new Date(),
+ payload,
+ };
+ });
+
+ await (tx ?? prisma).auditLogStaging.createMany({ data: rows });
+
+ return rows.map((row) => row.id);
+}
+
+/**
+ * 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
+ * match `AuditLogStagingPayloadSchema`.
+ */
+export function convertAuditLogStagingRowToClickhouse(
+ row: Pick<AuditLogStaging, "id" | "createdAt" | "payload">,
+): AuditLogRecordInsertType {
+ const event = AuditLogStagingPayloadSchema.parse(row.payload);
+ const { actor } = event;
+
+ return {
+ id: row.id,
+ timestamp: convertDateToClickhouseDateTime(row.createdAt),
+ org_id: event.orgId,
+ project_id: event.projectId ?? "",
+ event_kind: event.kind,
+ outcome: event.outcome,
+ outcome_reason: event.outcomeReason ?? "",
+ actor_type: actor.type,
+ user_id: actor.type === "SYSTEM" ? "" : (actor.userId ?? ""),
+ api_key_id: actor.type === "API_KEY" ? actor.apiKeyId : "",
+ actor_name: actor.name ?? "",
+ actor_email: actor.type === "SYSTEM" ? "" : (actor.email ?? ""),
+ user_org_role: actor.type === "USER" ? (actor.orgRole ?? "") : "",
+ user_project_role: actor.type === "USER" ? (actor.projectRole ?? "") : "",
+ resource_type: event.resourceType,
+ resource_id: event.resourceId ?? "",
+ resource_refs: event.resourceRefs,
+ action: event.action,
+ surface: event.surface ?? "",
+ route: event.route ?? "",
+ params: event.kind === "access" ? (event.params ?? "") : "",
+ result_count: event.kind === "access" ? (event.resultCount ?? 0) : 0,
+ before: event.kind === "change" ? (event.before ?? "") : "",
+ after: event.kind === "change" ? (event.after ?? "") : "",
+ ip: event.request?.ip ?? "",
+ user_agent: event.request?.userAgent ?? "",
+ request_id: event.request?.requestId ?? "",
+ };
+}
diff --git a/packages/shared/src/server/repositories/definitions.ts b/packages/shared/src/server/repositories/definitions.ts
index 04ba2995fa..5a696023b5 100644
--- a/packages/shared/src/server/repositories/definitions.ts
+++ b/packages/shared/src/server/repositories/definitions.ts
@@ -2,6 +2,7 @@ import z from "zod";
import type { IngestionAttribution } from "../ingestion/ingestionAttribution";
import { DEFAULT_TRACE_ENVIRONMENT } from "../ingestion/types";
import { toClickhouseDateTime } from "../clickhouse/client";
+import type { AuditLogStagingPayload } from "../../domain/auditLogs";
export const clickhouseStringDateSchema = z
.string()
@@ -581,3 +582,36 @@ export const eventRecordInsertSchema = eventRecordBaseSchema.extend({
event_ts: z.string(),
});
export type EventRecordInsertType = z.infer<typeof eventRecordInsertSchema>;
+
+// One row of the ClickHouse `audit_logs` table. Empty strings and zero stand in
+// for absent values, matching the column defaults. `project_id = ''` marks
+// organisation-level events.
+export type AuditLogRecordInsertType = {
+ id: string;
+ timestamp: string;
+ org_id: string;
+ project_id: string;
+ event_kind: AuditLogStagingPayload["kind"];
+ outcome: AuditLogStagingPayload["outcome"];
+ outcome_reason: string;
+ actor_type: AuditLogStagingPayload["actor"]["type"];
+ user_id: string;
+ api_key_id: string;
+ actor_name: string;
+ actor_email: string;
+ user_org_role: string;
+ user_project_role: string;
+ resource_type: string;
+ resource_id: string;
+ resource_refs: string[];
+ action: string;
+ surface: string;
+ route: string;
+ params: string;
+ result_count: number;
+ before: string;
+ after: string;
+ ip: string;
+ user_agent: string;
+ request_id: string;
+};
diff --git a/packages/shared/src/server/repositories/index.ts b/packages/shared/src/server/repositories/index.ts
index f55c331ee7..b9c7897837 100644
--- a/packages/shared/src/server/repositories/index.ts
+++ b/packages/shared/src/server/repositories/index.ts
@@ -28,3 +28,4 @@ export * from "./job-executions";
export * from "./daily-metrics";
export * from "./dataset-runs";
export * from "./score-configs";
+export * from "./auditLogs";
diff --git a/web/src/__tests__/server/audit-log-staging.servertest.ts b/web/src/__tests__/server/audit-log-staging.servertest.ts
new file mode 100644
index 0000000000..8fecfc3306
--- /dev/null
+++ b/web/src/__tests__/server/audit-log-staging.servertest.ts
@@ -0,0 +1,212 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, describe, expect, it } from "vitest";
+import { toAuditLogResourceRef } from "@langfuse/shared";
+import { prisma } from "@langfuse/shared/src/db";
+import {
+ clickhouseClient,
+ convertAuditLogStagingRowToClickhouse,
+ stageAuditLogEvents,
+ type AuditLogRecordInsertType,
+} from "@langfuse/shared/src/server";
+
+const queryAuditLogs = async (
+ query: string,
+ query_params: Record<string, string>,
+) => {
+ const result = await clickhouseClient().query({
+ query,
+ query_params,
+ format: "JSONEachRow",
+ });
+ return result.json<Record<string, unknown>>();
+};
+
+describe("audit log staging", () => {
+ const stagedIds: string[] = [];
+
+ afterAll(async () => {
+ await prisma.auditLogStaging.deleteMany({
+ where: { id: { in: stagedIds } },
+ });
+ });
+
+ it("stores staged events as audit_logs rows that resolve by resource ref", async () => {
+ const orgId = randomUUID();
+ const changeId = randomUUID();
+ const traceRef = toAuditLogResourceRef("trace", randomUUID());
+
+ const ids = await prisma.$transaction((tx) =>
+ stageAuditLogEvents(
+ [
+ {
+ id: changeId,
+ kind: "change",
+ orgId,
+ projectId: "project-1",
+ actor: {
+ type: "USER",
+ userId: "user-1",
+ name: "Ada Lovelace",
+ email: "[email protected]",
+ orgRole: "ADMIN",
+ projectRole: "OWNER",
+ },
+ resourceType: "prompt",
+ resourceId: "prompt-1",
+ action: "update",
+ before: { version: 1 },
+ after: { version: 2 },
+ surface: "trpc",
+ route: "prompts.update",
+ request: { ip: "203.0.113.7", userAgent: "curl/8.7.1" },
+ },
+ {
+ kind: "access",
+ orgId,
+ projectId: "project-1",
+ actor: { type: "API_KEY", apiKeyId: "api-key-1" },
+ resourceType: "observation",
+ action: "list",
+ resourceRefs: [
+ toAuditLogResourceRef("observation", "observation-1"),
+ traceRef,
+ ],
+ params: { limit: 50 },
+ resultCount: 1,
+ surface: "public-api",
+ route: "/api/public/v2/observations",
+ },
+ {
+ kind: "access",
+ orgId,
+ actor: { type: "SYSTEM", name: "blob-storage-export" },
+ resourceType: "trace",
+ action: "export",
+ outcome: "denied",
+ outcomeReason: "project not found",
+ },
+ ],
+ tx,
+ ),
+ );
+ stagedIds.push(...ids);
+ expect(ids[0]).toBe(changeId);
+
+ const staged = await prisma.auditLogStaging.findMany({
+ where: { id: { in: ids } },
+ });
+ const rows = ids.map((id) =>
+ convertAuditLogStagingRowToClickhouse(
+ staged.find((row) => row.id === id)!,
+ ),
+ );
+
+ expect(rows[0]).toMatchObject({
+ event_kind: "change",
+ actor_type: "USER",
+ user_id: "user-1",
+ api_key_id: "",
+ actor_name: "Ada Lovelace",
+ actor_email: "[email protected]",
+ user_org_role: "ADMIN",
+ user_project_role: "OWNER",
+ before: '{"version":1}',
+ after: '{"version":2}',
+ params: "",
+ ip: "203.0.113.7",
+ });
+ expect(rows[1]).toMatchObject({
+ event_kind: "access",
+ outcome: "success",
+ actor_type: "API_KEY",
+ user_id: "",
+ api_key_id: "api-key-1",
+ params: '{"limit":50}',
+ result_count: 1,
+ before: "",
+ });
+ expect(rows[2]).toMatchObject({
+ project_id: "",
+ outcome: "denied",
+ outcome_reason: "project not found",
+ actor_type: "SYSTEM",
+ actor_name: "blob-storage-export",
+ user_id: "",
+ api_key_id: "",
+ resource_refs: [],
+ });
+
+ await clickhouseClient().insert({
+ table: "audit_logs",
+ values: rows,
+ format: "JSONEachRow",
+ });
+
+ const stored = await queryAuditLogs(
+ "SELECT * EXCEPT inserted_at FROM audit_logs WHERE org_id = {orgId: String}",
+ { orgId },
+ );
+ const byId = (a: Record<string, unknown>, b: Record<string, unknown>) =>
+ String(a.id).localeCompare(String(b.id));
+ expect(stored.sort(byId)).toEqual(
+ [...rows].sort(byId) satisfies AuditLogRecordInsertType[],
+ );
+
+ const accessedTrace = await queryAuditLogs(
+ "SELECT id FROM audit_logs WHERE org_id = {orgId: String} AND has(resource_refs, {ref: String})",
+ { orgId, ref: traceRef },
+ );
+ expect(accessedTrace).toEqual([{ id: ids[1] }]);
+ });
+
+ it("discards staged rows when the caller's transaction rolls back", async () => {
+ const id = randomUUID();
+
+ await expect(
+ prisma.$transaction(async (tx) => {
+ await stageAuditLogEvents(
+ [
+ {
+ id,
+ kind: "change",
+ orgId: randomUUID(),
+ actor: { type: "USER", userId: "user-1" },
+ resourceType: "prompt",
+ resourceId: "prompt-1",
+ action: "delete",
+ },
+ ],
+ tx,
+ );
+ throw new Error("audited mutation failed");
+ }),
+ ).rejects.toThrow("audited mutation failed");
+
+ expect(
+ await prisma.auditLogStaging.findUnique({ where: { id } }),
+ ).toBeNull();
+ });
+
+ it("stages ids holding characters that jsonb cannot store", async () => {
+ const [id] = await stageAuditLogEvents([
+ {
+ kind: "access",
+ orgId: randomUUID(),
+ actor: { type: "API_KEY", apiKeyId: "api-key-1" },
+ resourceType: "trace",
+ resourceId: "trace-\u0000-1",
+ resourceRefs: [toAuditLogResourceRef("trace", "trace-\uD800-1")],
+ action: "read",
+ },
+ ]);
+ stagedIds.push(id);
+
+ const row = await prisma.auditLogStaging.findUniqueOrThrow({
+ where: { id },
+ });
+ expect(convertAuditLogStagingRowToClickhouse(row)).toMatchObject({
+ resource_id: "trace-�-1",
+ resource_refs: ["trace:trace-�-1"],
+ });
+ });
+});
diff --git a/web/src/__tests__/server/unit/getAuditRequestContext.servertest.ts b/web/src/__tests__/server/unit/getAuditRequestContext.servertest.ts
new file mode 100644
index 0000000000..728dd017d6
--- /dev/null
+++ b/web/src/__tests__/server/unit/getAuditRequestContext.servertest.ts
@@ -0,0 +1,85 @@
+import { describe, it, expect, vi } from "vitest";
+
+// getAuditRequestContext reads the trusted proxy count off `env` at call time,
+// so the cases mutate mockEnv.env.
+const mockEnv = vi.hoisted(() => ({
+ env: { LANGFUSE_TRUSTED_PROXY_COUNT: 0 },
+}));
+
+vi.mock("@/src/env.mjs", () => mockEnv);
+
+import { getAuditRequestContext } from "@/src/features/audit-logs/server";
+
+describe("getAuditRequestContext client IP", () => {
+ it.each([
+ {
+ name: "ignores X-Forwarded-For without trusted proxies",
+ trustedProxyCount: 0,
+ forwardedFor: "198.51.100.66",
+ remoteAddress: "::ffff:203.0.113.7",
+ expected: "203.0.113.7",
+ },
+ {
+ name: "skips client-supplied entries left of the trusted proxy's entry",
+ trustedProxyCount: 1,
+ forwardedFor: "198.51.100.66, 203.0.113.7",
+ remoteAddress: "10.0.0.1",
+ expected: "203.0.113.7",
+ },
+ {
+ name: "counts every trusted proxy from the right",
+ trustedProxyCount: 2,
+ forwardedFor: ["198.51.100.66, 203.0.113.7", "10.0.0.2"],
+ remoteAddress: "10.0.0.1",
+ expected: "203.0.113.7",
+ },
+ {
+ name: "falls back to the left-most entry when the chain is shorter",
+ trustedProxyCount: 3,
+ forwardedFor: "203.0.113.7, 10.0.0.2",
+ remoteAddress: "10.0.0.1",
+ expected: "203.0.113.7",
+ },
+ {
+ name: "uses the socket peer when no proxy forwarded the request",
+ trustedProxyCount: 1,
+ forwardedFor: undefined,
+ remoteAddress: "203.0.113.7",
+ expected: "203.0.113.7",
+ },
+ {
+ name: "strips the port from an IPv4 entry",
+ trustedProxyCount: 1,
+ forwardedFor: "198.51.100.66, 203.0.113.7:4711",
+ remoteAddress: "10.0.0.1",
+ expected: "203.0.113.7",
+ },
+ {
+ name: "strips brackets and port from an IPv6 entry",
+ trustedProxyCount: 1,
+ forwardedFor: "[2001:db8::7]:443",
+ remoteAddress: "10.0.0.1",
+ expected: "2001:db8::7",
+ },
+ {
+ name: "drops an entry that is not an IP address",
+ trustedProxyCount: 1,
+ forwardedFor: "203.0.113.7, unknown",
+ remoteAddress: "10.0.0.1",
+ expected: undefined,
+ },
+ ])(
+ "$name",
+ ({ trustedProxyCount, forwardedFor, remoteAddress, expected }) => {
+ mockEnv.env.LANGFUSE_TRUSTED_PROXY_COUNT = trustedProxyCount;
+
+ const context = getAuditRequestContext(
+ { "x-forwarded-for": forwardedFor, "user-agent": "curl/8.7.1" },
+ remoteAddress,
+ );
+
+ expect(context.ip).toBe(expected);
+ expect(context.userAgent).toBe("curl/8.7.1");
+ },
+ );
+});
diff --git a/web/src/env.mjs b/web/src/env.mjs
index 0078289cc6..2c93097310 100644
--- a/web/src/env.mjs
+++ b/web/src/env.mjs
@@ -658,6 +658,16 @@ export const env = createEnv({
.positive()
.default(150_000),
+ // Reverse proxies in front of the web container that append the client
+ // address to X-Forwarded-For. Audit events take the client IP from the
+ // N-th entry from the right, since entries further left are client-supplied.
+ // 0 ignores X-Forwarded-For and uses the socket peer address.
+ LANGFUSE_TRUSTED_PROXY_COUNT: z.coerce
+ .number()
+ .int()
+ .nonnegative()
+ .default(0),
+
// 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
@@ -1229,6 +1239,7 @@ export const env = createEnv({
process.env.LANGFUSE_MIGRATION_V4_WRITE_MODE,
LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT:
process.env.LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT,
+ LANGFUSE_TRUSTED_PROXY_COUNT: process.env.LANGFUSE_TRUSTED_PROXY_COUNT,
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/server/getAuditRequestContext.ts b/web/src/features/audit-logs/server/getAuditRequestContext.ts
new file mode 100644
index 0000000000..5561718500
--- /dev/null
+++ b/web/src/features/audit-logs/server/getAuditRequestContext.ts
@@ -0,0 +1,71 @@
+import { type IncomingHttpHeaders } from "node:http";
+import { isIP } from "node:net";
+import { type AuditRequestContext } from "@langfuse/shared";
+import { getActiveTraceId } from "@langfuse/shared/src/server";
+import { env } from "@/src/env.mjs";
+
+const IPV4 = String.raw`\d{1,3}(?:\.\d{1,3}){3}`;
+const BRACKETED_IPV6_WITH_OPTIONAL_PORT = /^\[([^\]]+)\](?::\d+)?$/;
+const IPV4_WITH_PORT = new RegExp(`^(${IPV4}):\\d+$`);
+const IPV4_MAPPED_IPV6 = new RegExp(`^::ffff:(${IPV4})$`, "i");
+
+/**
+ * Request metadata for audit events: the client IP, the User-Agent, and the
+ * active OTel trace id as request id (absent when the trace is not sampled).
+ *
+ * The client IP follows LANGFUSE_TRUSTED_PROXY_COUNT. With 0, X-Forwarded-For
+ * is ignored and `remoteAddress` (the socket peer) is used.
+ */
+export function getAuditRequestContext(
+ headers: IncomingHttpHeaders,
+ remoteAddress?: string,
+): AuditRequestContext {
+ return {
+ ip: getClientIp(headers, remoteAddress),
+ userAgent: headers["user-agent"] || undefined,
+ requestId: getActiveTraceId(),
+ };
+}
+
+// Each trusted proxy appends the address it received the request from, so
+// with N trusted proxies the client is the N-th X-Forwarded-For entry from the
+// right. Entries further left were sent by the client and can be forged.
+const getClientIp = (
+ headers: IncomingHttpHeaders,
+ remoteAddress: string | undefined,
+): string | undefined => {
+ const trustedProxyCount = env.LANGFUSE_TRUSTED_PROXY_COUNT;
+ if (trustedProxyCount === 0) return normalizeIp(remoteAddress);
+
+ const forwardedFor = headers["x-forwarded-for"];
+ const hops = (
+ Array.isArray(forwardedFor) ? forwardedFor.join(",") : (forwardedFor ?? "")
+ )
+ .split(",")
+ .map((hop) => hop.trim())
+ .filter((hop) => hop.length > 0);
+
+ // No header means the request did not pass through the proxies.
+ if (hops.length === 0) return normalizeIp(remoteAddress);
+
+ return normalizeIp(hops[Math.max(0, hops.length - trustedProxyCount)]);
+};
+
+// Accepts the address forms proxies and Node report: plain IPv4/IPv6, IPv4
+// with a port, bracketed IPv6 with an optional port, and IPv4-mapped IPv6
+// (how Node reports IPv4 peers on a dual-stack socket). Anything else is
+// dropped rather than stored.
+const normalizeIp = (raw: string | undefined): string | undefined => {
+ let value = raw?.trim();
+ if (!value) return undefined;
+
+ const bracketed = BRACKETED_IPV6_WITH_OPTIONAL_PORT.exec(value);
+ const withPort = IPV4_WITH_PORT.exec(value);
+ if (bracketed) value = bracketed[1];
+ else if (withPort) value = withPort[1];
+
+ const mapped = IPV4_MAPPED_IPV6.exec(value);
+ if (mapped) value = mapped[1];
+
+ return isIP(value) ? value : undefined;
+};
diff --git a/web/src/features/audit-logs/server/index.ts b/web/src/features/audit-logs/server/index.ts
index bca4ad52d2..bb630dd773 100644
--- a/web/src/features/audit-logs/server/index.ts
+++ b/web/src/features/audit-logs/server/index.ts
@@ -2,3 +2,4 @@
// writes through Prisma, so it has no client-safe surface: every caller is
// server code and reaches it through here.
export { auditLog } from "@/src/features/audit-logs/auditLog";
+export { getAuditRequestContext } from "@/src/features/audit-logs/server/getAuditRequestContext";