🪢 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): add audit_logs table, staging outbox and event contract (#18671)
Steffen Reuthere3d264c38ec7
diff --git a/.env.prod.example b/.env.prod.exampleindex 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=localhostdiff --git a/docker-compose.build.yml b/docker-compose.build.ymlindex 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.ymlindex 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.sqlnew file mode 100644index 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.prismaindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsindex 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.tsnew file mode 100644index 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.tsindex 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";