feat: offload log payloads to object storage

.env.example

@@ -31,6 +31,32 @@ STORAGE_REDIS_PORT=6479
 # STORAGE_REDIS_HOST=localhost
 STORAGE_REDIS_PASSWORD=change_this_redis_password
 
+# =============================================================================
+# PAYLOAD STORAGE (S3-COMPATIBLE OBJECT STORAGE)
+# =============================================================================
+
+# Offloads log payload blobs (messages, raw request/response, tool results)
+# to S3-compatible object storage; the log table keeps truncated previews plus
+# a blob reference. Leave PAYLOAD_STORAGE_S3_BUCKET unset to keep payloads in
+# Postgres (default; nothing else changes for self-hosters).
+#
+# Blob retention is enforced by a bucket lifecycle rule, not the app:
+#   MinIO: mc ilm rule add local/llmgateway-payloads --expire-days 30
+#   GCS:   gcloud storage buckets update gs://BUCKET --lifecycle-file=lifecycle.json
+# For GCS, use the S3-interoperability endpoint with HMAC keys from a service
+# account scoped to the bucket (roles/storage.objectAdmin):
+#   PAYLOAD_STORAGE_S3_ENDPOINT=https://storage.googleapis.com
+#   gcloud storage hmac create <service-account-email>
+#
+# Local MinIO (docker-compose) values:
+# PAYLOAD_STORAGE_S3_BUCKET=llmgateway-payloads
+# PAYLOAD_STORAGE_S3_ENDPOINT=http://localhost:9000
+# PAYLOAD_STORAGE_S3_REGION=us-east-1
+# PAYLOAD_STORAGE_S3_ACCESS_KEY_ID=minioadmin
+# PAYLOAD_STORAGE_S3_SECRET_ACCESS_KEY=minioadmin
+# PAYLOAD_STORAGE_S3_FORCE_PATH_STYLE=true
+# PAYLOAD_STORAGE_S3_PREFIX=
+
 # =============================================================================
 # SERVICE PORTS
 # =============================================================================

apps/api/src/routes/logs.spec.ts

@@ -1,11 +1,36 @@
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { randomUUID } from "node:crypto";
+
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	test,
+} from "vitest";
 
 import { app } from "@/index.js";
 import { createTestUser, deleteAll } from "@/testing.js";
 
 import { encryptProviderKeyForStorage } from "@llmgateway/actions";
 import { db, eq, tables } from "@llmgateway/db";
 import { hashApiKeyForStorage } from "@llmgateway/shared/api-key-hash";
+import {
+	buildPayloadKey,
+	ensurePayloadStorageBucket,
+	putLogPayload,
+} from "@llmgateway/shared/payload-storage";
+
+const PAYLOAD_ENV_KEYS = [
+	"PAYLOAD_STORAGE_S3_BUCKET",
+	"PAYLOAD_STORAGE_S3_ENDPOINT",
+	"PAYLOAD_STORAGE_S3_REGION",
+	"PAYLOAD_STORAGE_S3_ACCESS_KEY_ID",
+	"PAYLOAD_STORAGE_S3_SECRET_ACCESS_KEY",
+	"PAYLOAD_STORAGE_S3_FORCE_PATH_STYLE",
+	"PAYLOAD_STORAGE_S3_PREFIX",
+] as const;
 
 describe("logs route", () => {
 	let token: string;
@@ -982,4 +1007,141 @@ describe("logs route", () => {
 			expect(ids).toContain("teammate-log-id");
 		});
 	});
+
+	describe("payload storage", () => {
+		const envSnapshot = Object.fromEntries(
+			PAYLOAD_ENV_KEYS.map((key) => [key, process.env[key]]),
+		);
+
+		beforeAll(async () => {
+			process.env.PAYLOAD_STORAGE_S3_BUCKET = "llmgateway-payloads";
+			// MINIO_PORT is set by offset per-worktree stacks (see docker-compose.yml).
+			process.env.PAYLOAD_STORAGE_S3_ENDPOINT = `http://localhost:${process.env.MINIO_PORT ?? "9000"}`;
+			process.env.PAYLOAD_STORAGE_S3_REGION = "us-east-1";
+			process.env.PAYLOAD_STORAGE_S3_ACCESS_KEY_ID = "minioadmin";
+			process.env.PAYLOAD_STORAGE_S3_SECRET_ACCESS_KEY = "minioadmin";
+			process.env.PAYLOAD_STORAGE_S3_FORCE_PATH_STYLE = "true";
+			delete process.env.PAYLOAD_STORAGE_S3_PREFIX;
+			await ensurePayloadStorageBucket();
+		});
+
+		afterAll(() => {
+			for (const key of PAYLOAD_ENV_KEYS) {
+				const value = envSnapshot[key];
+				if (value === undefined) {
+					Reflect.deleteProperty(process.env, key);
+				} else {
+					process.env[key] = value;
+				}
+			}
+		});
+
+		async function insertOffloadedLog(payloadRef: string) {
+			await db.insert(tables.log).values({
+				id: "test-log-offloaded",
+				requestId: "test-log-offloaded",
+				organizationId: "test-org-id",
+				projectId: "test-project-id",
+				apiKeyId: "test-api-key-id",
+				duration: 100,
+				requestedModel: "gpt-4",
+				requestedProvider: "openai",
+				usedModel: "gpt-4",
+				usedProvider: "openai",
+				responseSize: 1000,
+				content: "preview content… [truncated]",
+				messages: [{ role: "user", content: "preview… [truncated]" }],
+				toolResults: null,
+				rawRequest: null,
+				finishReason: "stop",
+				mode: "api-keys",
+				usedMode: "api-keys",
+				payloadRef,
+			});
+		}
+
+		test("detail route hydrates offloaded payload fields from the blob", async () => {
+			const payloadRef = buildPayloadKey(
+				"test-org-id",
+				"test-project-id",
+				`hydrate-${randomUUID()}`,
+			);
+			const fullMessages = [
+				{ role: "user", content: "the full original message" },
+			];
+			await putLogPayload(payloadRef, {
+				messages: fullMessages,
+				content: "the full original response content",
+				toolResults: [{ output: "full tool output" }],
+				rawRequest: { body: { debug: true } },
+			});
+			await insertOffloadedLog(payloadRef);
+
+			const res = await app.request("/logs/test-log-offloaded", {
+				method: "GET",
+				headers: {
+					Cookie: token,
+				},
+			});
+
+			expect(res.status).toBe(200);
+			const json = await res.json();
+			expect(json.log.messages).toEqual(fullMessages);
+			expect(json.log.content).toBe("the full original response content");
+			expect(json.log.toolResults).toEqual([{ output: "full tool output" }]);
+			expect(json.log.rawRequest).toEqual({ body: { debug: true } });
+			expect("payloadRef" in json.log).toBe(false);
+			expect(json.log.payloadUnavailable).toBeUndefined();
+		});
+
+		test("detail route degrades to previews when the blob is gone", async () => {
+			await insertOffloadedLog(
+				buildPayloadKey(
+					"test-org-id",
+					"test-project-id",
+					`missing-${randomUUID()}`,
+				),
+			);
+
+			const res = await app.request("/logs/test-log-offloaded", {
+				method: "GET",
+				headers: {
+					Cookie: token,
+				},
+			});
+
+			expect(res.status).toBe(200);
+			const json = await res.json();
+			expect(json.log.payloadUnavailable).toBe(true);
+			expect(json.log.content).toBe("preview content… [truncated]");
+			expect(json.log.messages).toEqual([
+				{ role: "user", content: "preview… [truncated]" },
+			]);
+			expect("payloadRef" in json.log).toBe(false);
+		});
+
+		test("list responses omit detail-only payload columns", async () => {
+			const params = new URLSearchParams({ projectId: "test-project-id" });
+			const res = await app.request("/logs?" + params, {
+				method: "GET",
+				headers: {
+					Cookie: token,
+				},
+			});
+
+			expect(res.status).toBe(200);
+			const json = await res.json();
+			expect(json.logs.length).toBeGreaterThan(0);
+			for (const entry of json.logs) {
+				expect("rawRequest" in entry).toBe(false);
+				expect("rawResponse" in entry).toBe(false);
+				expect("upstreamRequest" in entry).toBe(false);
+				expect("upstreamResponse" in entry).toBe(false);
+				expect("responsesApiData" in entry).toBe(false);
+				expect("payloadRef" in entry).toBe(false);
+			}
+			// Preview-backed columns still serve list views.
+			expect(json.logs[0].content).toBeTruthy();
+		});
+	});
 });

apps/api/src/routes/logs.ts

@@ -34,6 +34,11 @@ import {
 	toolResults,
 	tools,
 } from "@llmgateway/db";
+import { logger } from "@llmgateway/logger";
+import {
+	getLogPayload,
+	isPayloadStorageEnabled,
+} from "@llmgateway/shared/payload-storage";
 import { buildSignedGatewayVideoLogContentUrl } from "@llmgateway/shared/video-access";
 
 import type { ServerTypes } from "@/vars.js";
@@ -56,16 +61,44 @@ const {
 	...publicLogColumns
 } = getTableColumns(tables.log);
 
+// Detail-only payload columns: rendered nowhere in list views and, on legacy
+// rows written before payload offloading, still multi-MB inline — the list
+// query skips them entirely. payloadRef is transport-internal (resolved into
+// the payload fields by the detail handler) and never leaves the API.
+const {
+	rawRequest: _rawRequest,
+	rawResponse: _rawResponse,
+	upstreamRequest: _upstreamRequest,
+	upstreamResponse: _upstreamResponse,
+	responsesApiData: _responsesApiData,
+	payloadRef: _payloadRef,
+	...listLogColumns
+} = publicLogColumns;
+
 const logSelection = {
 	...publicLogColumns,
 	organizationName: tables.organization.name,
 	projectName: tables.project.name,
 	apiKeyName: tables.apiKey.description,
 };
 
-async function enrichLogsWithVideoContentUrls<T extends LogRecord>(
-	logEntries: T[],
-): Promise<T[]> {
+const logListSelection = {
+	...listLogColumns,
+	organizationName: tables.organization.name,
+	projectName: tables.project.name,
+	apiKeyName: tables.apiKey.description,
+};
+
+async function enrichLogsWithVideoContentUrls<
+	T extends Pick<
+		LogRecord,
+		| "id"
+		| "content"
+		| "videoOutputCost"
+		| "videoDownloadCount"
+		| "lastVideoDownloadedAt"
+	>,
+>(logEntries: T[]): Promise<T[]> {
 	const hasVideoLogState = (log: T) =>
 		log.videoOutputCost !== null ||
 		log.videoDownloadCount > 0 ||
@@ -234,6 +267,10 @@ const logSchema = z.object({
 	gatewayContentFilterResponse: gatewayContentFilterResponseSchema
 		.nullable()
 		.optional(),
+	// True when the row's offloaded payload blob could not be fetched (e.g.
+	// already deleted by the bucket lifecycle rule); the payload fields then
+	// carry the stored previews instead of the full data.
+	payloadUnavailable: z.boolean().optional(),
 });
 
 // GET /logs/:id - Fetch a single log by ID
@@ -710,7 +747,7 @@ logs.openapi(get, async (c) => {
 
 	// Execute the query using select
 	let dbQuery = db
-		.select(logSelection)
+		.select(logListSelection)
 		.from(tables.log)
 		.leftJoin(
 			tables.organization,
@@ -986,5 +1023,34 @@ logs.openapi(getById, async (c) => {
 		});
 	}
 
-	return c.json({ log });
+	// Hydrate offloaded payload fields from object storage. The blob wins over
+	// the truncated previews stored in the row; a missing or unreadable blob
+	// degrades to the previews with payloadUnavailable set rather than failing
+	// the whole detail view.
+	let payloadUnavailable = false;
+	if (log.payloadRef && isPayloadStorageEnabled()) {
+		let payload: Record<string, unknown> | null = null;
+		try {
+			payload = await getLogPayload(log.payloadRef);
+		} catch (error) {
+			logger.warn("Failed to fetch log payload from storage", {
+				payloadRef: log.payloadRef,
+				error,
+			});
+		}
+		if (payload) {
+			log = { ...log, ...(payload as Partial<typeof log>) };
+		} else {
+			payloadUnavailable = true;
+		}
+	}
+
+	const { payloadRef: _logPayloadRef, ...logForResponse } = log;
+
+	return c.json({
+		log: {
+			...logForResponse,
+			...(payloadUnavailable ? { payloadUnavailable: true } : {}),
+		},
+	});
 });