7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
feat(observability): expose execution_id in response bodies and log the caller (#1103)
suantea (asuan_suan)c67f0857462e
diff --git a/server/src/__tests__/db/migrate/roundtrip.test.ts b/server/src/__tests__/db/migrate/roundtrip.test.tsindex ab01aefd..34ba764e 100644--- a/server/src/__tests__/db/migrate/roundtrip.test.ts+++ b/server/src/__tests__/db/migrate/roundtrip.test.ts@@ -34,6 +34,7 @@ const ATTEMPT_KEY_LABEL_FILENAME = '20260823_000003_attempt_key_label.ts';const PROFILE_AUTO_INCLUDE_FILENAME = '20260823_000004_profile_auto_include.ts';const IDEMPOTENCY_CLAIMS_FILENAME = '20260901_000001_idempotency_claims.ts';const QUOTA_OBSERVATION_LOOKUP_FILENAME = '20260901_000002_quota_observation_lookup.ts';+const REQUEST_CALLER_FILENAME = '20260901_000003_request_caller.ts';const ANALYTICS_LATENCY_PERCENTILE_INDEX_FILENAME = '20260902_000001_analytics_latency_percentile_index.ts';const MCP_ENABLED_DEFAULT_FILENAME = '20260903_000001_mcp_enabled_default.ts';const RESPONSE_CACHE_FILENAME = '20260903_000002_response_cache.ts';@@ -117,6 +118,7 @@ describe('migration round trip', () => {PROFILE_AUTO_INCLUDE_FILENAME,IDEMPOTENCY_CLAIMS_FILENAME,QUOTA_OBSERVATION_LOOKUP_FILENAME,+ REQUEST_CALLER_FILENAME,ANALYTICS_LATENCY_PERCENTILE_INDEX_FILENAME,MCP_ENABLED_DEFAULT_FILENAME,RESPONSE_CACHE_FILENAME,diff --git a/server/src/__tests__/lib/request-caller.test.ts b/server/src/__tests__/lib/request-caller.test.tsnew file mode 100644index 00000000..0deceb12--- /dev/null+++ b/server/src/__tests__/lib/request-caller.test.ts@@ -0,0 +1,49 @@+import { describe, it, expect, beforeEach, vi } from 'vitest';++// #1102: request analytics gain a `caller` dimension ('http' | 'mcp' | 'web')+// so self-hosters can tell which gateway pathway produced a request. The+// migration adds the column; logRequest writes it; NULL for legacy callers.++vi.mock('../../services/request-retention.js', () => ({+ pruneRequestAnalytics: vi.fn(),+}));++import { initDb, getDb } from '../../db/index.js';+import { logRequest } from '../../lib/request-log.js';++interface RequestRow {+ platform: string;+ model_id: string;+ caller: string | null;+ status: string;+}++function latestRequest(): RequestRow | undefined {+ return getDb().prepare(+ `SELECT platform, model_id, caller, status FROM requests ORDER BY id DESC LIMIT 1`,+ ).get() as RequestRow | undefined;+}++describe('logRequest caller dimension (#1102)', () => {+ beforeEach(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ });++ it('persists the caller when provided', () => {+ logRequest('groq', 'llama-3.3-70b', 7, 'success', 10, 5, 120, null, null, null, null, 'http');+ expect(latestRequest()?.caller).toBe('http');+ });++ it('persists mcp and web callers', () => {+ logRequest('groq', 'llama-3.3-70b', 7, 'success', 10, 5, 120, null, null, null, null, 'mcp');+ expect(latestRequest()?.caller).toBe('mcp');+ logRequest('groq', 'llama-3.3-70b', 7, 'success', 10, 5, 120, null, null, null, null, 'web');+ expect(latestRequest()?.caller).toBe('web');+ });++ it('writes NULL for legacy callers that do not pass a caller', () => {+ logRequest('groq', 'llama-3.3-70b', 7, 'success', 10, 5, 120, null);+ expect(latestRequest()?.caller).toBeNull();+ });+});diff --git a/server/src/db/migrate/defaults.ts b/server/src/db/migrate/defaults.tsindex 4a284c01..9c95d1dc 100644--- a/server/src/db/migrate/defaults.ts+++ b/server/src/db/migrate/defaults.ts@@ -28,6 +28,7 @@ import * as backupsTable from '../migrations/20260823_000002_backups_table.js';import * as attemptKeyLabel from '../migrations/20260823_000003_attempt_key_label.js';import * as profileAutoInclude from '../migrations/20260823_000004_profile_auto_include.js';import * as idempotencyClaims from '../migrations/20260901_000001_idempotency_claims.js';+import * as requestCaller from '../migrations/20260901_000003_request_caller.js';import * as quotaObservationLookup from '../migrations/20260901_000002_quota_observation_lookup.js';import * as analyticsLatencyPercentileIndex from '../migrations/20260902_000001_analytics_latency_percentile_index.js';import * as mcpEnabledDefault from '../migrations/20260903_000001_mcp_enabled_default.js';@@ -73,6 +74,7 @@ export const ATTEMPT_KEY_LABEL_FILENAME = '20260823_000003_attempt_key_label.ts'export const PROFILE_AUTO_INCLUDE_FILENAME = '20260823_000004_profile_auto_include.ts';export const IDEMPOTENCY_CLAIMS_FILENAME = '20260901_000001_idempotency_claims.ts';export const QUOTA_OBSERVATION_LOOKUP_FILENAME = '20260901_000002_quota_observation_lookup.ts';+export const REQUEST_CALLER_FILENAME = '20260901_000003_request_caller.ts';export const ANALYTICS_LATENCY_PERCENTILE_INDEX_FILENAME = '20260902_000001_analytics_latency_percentile_index.ts';export const MCP_ENABLED_DEFAULT_FILENAME = '20260903_000001_mcp_enabled_default.ts';export const RESPONSE_CACHE_FILENAME = '20260903_000002_response_cache.ts';@@ -108,6 +110,7 @@ export const DEFAULT_MIGRATIONS: readonly DefaultMigration[] = [{ filename: PROFILE_AUTO_INCLUDE_FILENAME, module: profileAutoInclude },{ filename: IDEMPOTENCY_CLAIMS_FILENAME, module: idempotencyClaims },{ filename: QUOTA_OBSERVATION_LOOKUP_FILENAME, module: quotaObservationLookup },+ { filename: REQUEST_CALLER_FILENAME, module: requestCaller },{ filename: ANALYTICS_LATENCY_PERCENTILE_INDEX_FILENAME, module: analyticsLatencyPercentileIndex },{ filename: MCP_ENABLED_DEFAULT_FILENAME, module: mcpEnabledDefault },{ filename: RESPONSE_CACHE_FILENAME, module: responseCache },diff --git a/server/src/db/migrations/20260901_000003_request_caller.ts b/server/src/db/migrations/20260901_000003_request_caller.tsnew file mode 100644index 00000000..7acc9494--- /dev/null+++ b/server/src/db/migrations/20260901_000003_request_caller.ts@@ -0,0 +1,29 @@+// Migration: caller dimension on request analytics+// Created: 2026-09-01+//+// DOWN: reversible+//+// Request log rows (requests table) gain a `caller` column so self-hosters can+// tell which pathway produced a request: 'http' (OpenAI-compatible endpoints),+// 'mcp' (/mcp JSON-RPC), or 'web' (dashboard API). Pairs with the top-level+// `execution_id` on response bodies (see routes/proxy.ts) — given an id from a+// client error you can look up the row and see its caller at a glance.++import type { Db } from '../types.js';++function hasColumn(db: Db, table: string, column: string): boolean {+ const row = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;+ return row.some(c => c.name === column);+}++export function up(db: Db): void {+ if (!hasColumn(db, 'requests', 'caller')) {+ db.prepare('ALTER TABLE requests ADD COLUMN caller TEXT').run();+ }+}++export function down(db: Db): void {+ if (hasColumn(db, 'requests', 'caller')) {+ db.prepare('ALTER TABLE requests DROP COLUMN caller').run();+ }+}diff --git a/server/src/lib/request-log.ts b/server/src/lib/request-log.tsindex 06fe8aef..7a1c53d6 100644--- a/server/src/lib/request-log.ts+++ b/server/src/lib/request-log.ts@@ -67,6 +67,10 @@ export function logRequest(// lib/served-model.ts). NULL when it matches or the provider reported// nothing usable, so the column stays empty in the healthy case.servedModel: string | null = null,+ // Which gateway pathway produced this request: 'http' (OpenAI-compatible+ // endpoints), 'mcp' (/mcp JSON-RPC), or 'web' (dashboard API). Lets+ // analytics tell paths apart when debugging. NULL for legacy callers.+ caller: string | null = null,) {try {const db = getDb();@@ -75,9 +79,9 @@ export function logRequest(const client = getClientContext();const tx = db.transaction(() => {const insert = db.prepare(`- INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, ttfb_ms, requested_model, served_model, client_ip, client_user_agent, client_agent)- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)- `).run(platform, modelId, keyId, status, inputTokens, outputTokens, latencyMs, error, ttfbMs, requestedModel, servedModel, client.ip, client.userAgent, client.agent);+ INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, ttfb_ms, requested_model, served_model, client_ip, client_user_agent, client_agent, caller)+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ `).run(platform, modelId, keyId, status, inputTokens, outputTokens, latencyMs, error, ttfbMs, requestedModel, servedModel, client.ip, client.userAgent, client.agent, caller);// Report the row id back to the fallback loop's attempt trace (if one is// active): the LAST id noted during a loop run is the terminal row thediff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.tsindex 369eeb0c..8633ca0d 100644--- a/server/src/routes/proxy.ts+++ b/server/src/routes/proxy.ts@@ -1264,7 +1264,7 @@ proxyRouter.post('/completions', async (req: Request, res: Response) => {inputTokens: estimatedInputTokens,outputTokens: totalOutputTokens,});- logRequest(route.platform, route.modelId, route.keyId, 'success', estimatedInputTokens, totalOutputTokens, Date.now() - start, null, ttfbMs, pinnedModelId);+ logRequest(route.platform, route.modelId, route.keyId, 'success', estimatedInputTokens, totalOutputTokens, Date.now() - start, null, ttfbMs, pinnedModelId, null, 'http');return 'done';} catch (streamErr: any) {// Client abort mid-stream: the pump's own `if (clientGone) break`@@ -1287,7 +1287,7 @@ proxyRouter.post('/completions', async (req: Request, res: Response) => {latencyMs: Date.now() - start,error: sanitizeProviderErrorMessage(streamErr.message),});- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, sanitizeProviderErrorMessage(streamErr.message), ttfbMs, pinnedModelId);+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, sanitizeProviderErrorMessage(streamErr.message), ttfbMs, pinnedModelId, null, 'http');return 'committed';}throw streamErr;@@ -1357,7 +1357,7 @@ proxyRouter.post('/completions', async (req: Request, res: Response) => {inputTokens: promptTokens,outputTokens: completionTokens,});- logRequest(route.platform, route.modelId, route.keyId, 'success', promptTokens, completionTokens, Date.now() - start, null, null, pinnedModelId);+ logRequest(route.platform, route.modelId, route.keyId, 'success', promptTokens, completionTokens, Date.now() - start, null, null, pinnedModelId, null, 'http');return 'done';},logFailure: (route, err, attempt) => {@@ -1372,7 +1372,7 @@ proxyRouter.post('/completions', async (req: Request, res: Response) => {latencyMs: latency,error: safeError,});- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, latency, safeError, null, pinnedModelId);+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, latency, safeError, null, pinnedModelId, null, 'http');},onFatal: (route, err, attempt) => {setFallbackHeaders(res, attempt, attemptLog);@@ -1396,12 +1396,12 @@ proxyRouter.post('/completions', async (req: Request, res: Response) => {}setFallbackHeaders(res, info.attempts.length, info.attempts);setExhaustionHeaders(res, exhaustion);- res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion) });+ res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion), execution_id: requestGroupId });},onExhausted: (exhaustion, info) => {setFallbackHeaders(res, info.attempts.length, info.attempts);setExhaustionHeaders(res, exhaustion);- res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion) });+ res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion), execution_id: requestGroupId });},});});@@ -1434,6 +1434,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {message: `Invalid request: ${detail}`,type: 'invalid_request_error',},+ execution_id: requestGroupId,});return;}@@ -2180,7 +2181,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {latencyMs: Date.now() - start,error: sanitizeProviderErrorMessage(String(msg)),});- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, `in-band error frame: ${sanitizeProviderErrorMessage(String(msg))}`, ttfbMs, pinnedModelId);+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, `in-band error frame: ${sanitizeProviderErrorMessage(String(msg))}`, ttfbMs, pinnedModelId, null, 'http');return 'committed';}@@ -2467,7 +2468,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {outputTokens,});logRequest(route.platform, route.modelId, route.keyId, 'success', inputTokens, outputTokens, Date.now() - start, null, ttfbMs, pinnedModelId,- observeServedModel({ platform: route.platform, requestedModel: route.modelId, servedModel: upstreamModel }));+ observeServedModel({ platform: route.platform, requestedModel: route.modelId, servedModel: upstreamModel }), 'http');return 'done';} catch (streamErr: any) {// Client abort mid-stream: the pump's own `if (clientGone) break`@@ -2492,7 +2493,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {latencyMs: Date.now() - start,error: sanitizeProviderErrorMessage(streamErr.message),});- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, sanitizeProviderErrorMessage(streamErr.message), ttfbMs, pinnedModelId);+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, sanitizeProviderErrorMessage(streamErr.message), ttfbMs, pinnedModelId, null, 'http');return 'committed';}// Headers never sent — bubble to the shared loop, which cooldowns this@@ -2692,7 +2693,10 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {);}- res.json(outboundBody);+ // #1102: expose the execution id in the body so clients (incl. AI+ // agents that ignore headers) can trace this response to its analytics+ // attempt trail. Additive — OpenAI clients ignore unknown fields.+ res.json({ execution_id: requestGroupId, ...outboundBody });// Cache the freshly-generated answer so an identical later request is// served from memory without spending another free-tier slot. A@@ -2720,7 +2724,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {outputTokens: completionTokens,});logRequest(route.platform, route.modelId, route.keyId, 'success', promptTokens, completionTokens, Date.now() - start, null, null, pinnedModelId,- observeServedModel({ platform: route.platform, requestedModel: route.modelId, servedModel: upstreamModel }));+ observeServedModel({ platform: route.platform, requestedModel: route.modelId, servedModel: upstreamModel }), 'http');return 'done';}},@@ -2736,7 +2740,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {latencyMs: latency,error: safeError,});- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, latency, safeError, null, pinnedModelId);+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, latency, safeError, null, pinnedModelId, null, 'http');},onFatal: (route, err, attempt) => {// Non-retryable error (bare 4xx, etc.): don't retry.@@ -2764,12 +2768,12 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {}setFallbackHeaders(res, info.attempts.length, info.attempts);setExhaustionHeaders(res, exhaustion);- res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion) });+ res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion), execution_id: requestGroupId });},onExhausted: (exhaustion, info) => {setFallbackHeaders(res, info.attempts.length, info.attempts);setExhaustionHeaders(res, exhaustion);- res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion) });+ res.status(exhaustion.status).json({ error: exhaustionErrorPayload(exhaustion), execution_id: requestGroupId });},});});