Skip to content

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 the
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 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 });
},
});
});