@timo972/cc-router 0.12.1 → 0.12.2-rc.0

package/dist/providers/openai/usage-fetch.js

@@ -1,6 +1,7 @@
 import { applyCodexRateLimits } from "./account-state.js";
 import { parseCodexUsagePayload } from "./usage.js";
 import { UsageRefresher } from "../../proxy/usage-refresher.js";
+import { classifyExpectedRuntimeFailure, httpOutcome, recordRuntimeError, recordUpstreamStatus, withTelemetrySpan, } from "../../telemetry/facade.js";
 /**
  * The endpoint the Codex CLI's own backend client reads rate limits from
  * (codex-rs/backend-client, ChatGPT path style). Answers a bearer-only GET
@@ -8,7 +9,17 @@ import { UsageRefresher } from "../../proxy/usage-refresher.js";
  * makes usage visible without burning a request through /codex/responses.
  */
 export const CODEX_USAGE_ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
-export async function fetchCodexUsage(account, options = {}) {
+export function fetchCodexUsage(account, options = {}) {
+    return withTelemetrySpan("provider.usage_refresh", { provider: "openai" }, async (span) => {
+        const result = await runCodexUsageFetch(account, options, span);
+        // Failure paths classify the span where the status or error is known;
+        // this only covers the ones that could not (e.g. a malformed body).
+        if (!result.ok)
+            span.fail();
+        return result;
+    });
+}
+async function runCodexUsageFetch(account, options, span) {
     const fetchImpl = options.fetch ?? globalThis.fetch;
     const now = options.now ?? Date.now;
     let response;
@@ -18,9 +29,15 @@ export async function fetchCodexUsage(account, options = {}) {
             signal: AbortSignal.timeout(10_000),
         });
     }
-    catch {
+    catch (error) {
+        recordRuntimeError(error, { operation: "provider.usage_refresh", provider: "openai" });
+        span.fail({ outcome: classifyExpectedRuntimeFailure(error) === "timeout" ? "timeout" : "upstream_error" });
         return { ok: false, reason: "network" };
     }
+    if (!response.ok) {
+        recordUpstreamStatus("provider.usage_refresh", "openai", response.status);
+        span.fail({ httpStatusCode: response.status, outcome: httpOutcome(response.status) });
+    }
     if (response.status === 401 || response.status === 403)
         return { ok: false, reason: "auth" };
     if (!response.ok)

package/dist/proxy/anthropic-messages-route.js

@@ -5,8 +5,12 @@ import { acquireRequestRoute, applyUpstreamFailureRoutingDetailed, routeFailureD
 import { EmptyPoolError, NoEligibleAccountError } from "./token-pool.js";
 import { applyRateLimitHeaders } from "../providers/anthropic/rate-limit-headers.js";
 import { attachAnthropicResponseCapture } from "./anthropic-response-capture.js";
+import { TRACE_CONTEXT_HEADERS } from "./anthropic-proxy.js";
 import { boundModelId, stats } from "./stats.js";
 import { logError, logRoute } from "./logger.js";
+import { annotateActiveSpan, classifyExpectedRuntimeFailure, modelFamilyOf, recordRuntimeError, recordUpstreamStatus, settleProxyRequestSpan, startTelemetrySpan, } from "../telemetry/facade.js";
+/** How long a provider span may wait for a compressed body's usage after the response closed. */
+const USAGE_SETTLE_GRACE_MS = 1_000;
 import { MAX_UPSTREAM_ATTEMPTS, RETRY_REFRESH_TIMEOUT_MS, SAME_ACCOUNT_RETRY_DELAY_MS, boundedWait, isRetryableUpstreamStatus, retryDelay, } from "./upstream-retry.js";
 const OAUTH_BETA = "oauth-2025-04-20";
 /**
@@ -44,6 +48,8 @@ function buildUpstreamHeaders(req, target, account, bodyLength) {
     delete headers["content-length"];
     delete headers["transfer-encoding"];
     delete headers["x-api-key"];
+    for (const header of TRACE_CONTEXT_HEADERS)
+        delete headers[header];
     headers["connection"] = "close";
     headers["host"] = target.host;
     headers["authorization"] = `Bearer ${account.tokens.accessToken}`;
@@ -90,7 +96,9 @@ function forwardAttempt(opts) {
         });
         upstreamRequest.on("error", reject);
         upstreamRequest.on("timeout", () => {
-            upstreamRequest.destroy(new Error(`Upstream request timed out after ${opts.timeoutMs}ms`));
+            // The `code` lets telemetry classify this as an expected timeout; the
+            // message and the client-facing response are unchanged.
+            upstreamRequest.destroy(Object.assign(new Error(`Upstream request timed out after ${opts.timeoutMs}ms`), { code: "ETIMEDOUT" }));
         });
     });
     upstreamRequest.end(opts.body);
@@ -103,7 +111,7 @@ function forwardAttempt(opts) {
  * its HTTP/1.0 accommodations, so moving /v1/messages off the generic proxy
  * changes nothing about what a client receives.
  */
-function relayUpstreamResponse(upstream, req, res) {
+function relayUpstreamResponse(upstream, req, res, onUpstreamFailure) {
     if (req.httpVersion === "1.0") {
         delete upstream.headers["transfer-encoding"];
         upstream.headers["connection"] = req.headers["connection"] ?? "close";
@@ -122,6 +130,9 @@ function relayUpstreamResponse(upstream, req, res) {
     // tear the client connection down rather than ending it cleanly, so the
     // client sees a broken transfer instead of a silently truncated body.
     upstream.once("error", () => {
+        // Recorded before the downstream teardown, which would otherwise look
+        // like a client hang-up to the response's own close listener.
+        onUpstreamFailure?.();
         if (!res.writableEnded)
             res.destroy();
     });
@@ -167,8 +178,22 @@ export function mountAnthropicMessagesRoute(app, opts) {
                 ? "desktop"
                 : "api";
         const model = boundModelId(context?.requestedModel ?? "-");
+        const modelFamily = modelFamilyOf(model);
+        const streaming = req.body?.stream === true;
         const startedAt = now();
         stats.totalRequests++;
+        annotateActiveSpan("proxy.request", {
+            provider: "anthropic",
+            route: "messages",
+            modelFamily,
+            requestSource: source,
+            streaming,
+            accountPoolSize: opts.pool.getAll().length,
+        });
+        /** The request span's final verdict; the middleware ends the span from it. */
+        const settleRequest = (outcome, extra = {}) => {
+            settleProxyRequestSpan(res, { ...extra, outcome, operationDurationMs: now() - startedAt });
+        };
         // A client that hangs up takes the in-flight upstream attempt (and any
         // pending retry) with it. `writableEnded` guards the normal-completion
         // close; only a premature close is a disconnect.
@@ -188,6 +213,23 @@ export function mountAnthropicMessagesRoute(app, opts) {
         for (let attempt = 1;; attempt++) {
             const account = route.account;
             const attemptStartedAt = now();
+            const attemptSpan = startTelemetrySpan("provider.inference", {
+                provider: "anthropic",
+                route: "messages",
+                modelFamily,
+                streaming,
+                attempt,
+            });
+            /** Close this attempt's span exactly once, on the outcome it ended with. */
+            const endAttempt = (outcome, extra = {}) => {
+                attemptSpan.annotate({
+                    ...extra,
+                    outcome,
+                    attempt,
+                    operationDurationMs: now() - attemptStartedAt,
+                });
+                attemptSpan.end(outcome === "complete" ? "ok" : "error");
+            };
             req._ccAccount = account;
             logRoute(account.id, account.requestCount, Math.round((account.tokens.expiresAt - now()) / 60_000));
             const forwarded = forwardAttempt({
@@ -209,10 +251,20 @@ export function mountAnthropicMessagesRoute(app, opts) {
                 // is a cancellation, not an upstream failure — there is no client
                 // left to receive a 502, and the generic proxy does not log client
                 // resets either.
-                if (clientGone.signal.aborted || res.writableEnded)
+                if (clientGone.signal.aborted || res.writableEnded) {
+                    endAttempt("cancelled", { streamOutcome: "cancelled" });
+                    settleRequest("cancelled", { streamOutcome: "cancelled", attempt });
                     return;
+                }
                 const message = error instanceof Error ? error.message : String(error);
                 stats.totalErrors++;
+                recordRuntimeError(error, { operation: "provider.inference", provider: "anthropic" }, {
+                    attempt,
+                    durationMs: now() - attemptStartedAt,
+                });
+                const forwardOutcome = classifyExpectedRuntimeFailure(error) === "timeout"
+                    ? "timeout"
+                    : "upstream_error";
                 logError("proxy", 0, message);
                 recordActivity({
                     ts: attemptStartedAt,
@@ -234,10 +286,18 @@ export function mountAnthropicMessagesRoute(app, opts) {
                         error: { type: "proxy_error", message },
                     });
                 }
+                endAttempt(forwardOutcome, { httpStatusCode: 502, streamOutcome: forwardOutcome });
+                settleRequest(forwardOutcome, { httpStatusCode: 502, attempt });
                 return;
             }
             req.socket.setTimeout(0);
             const status = upstream.statusCode ?? 0;
+            if (status === 401 || status === 403 || status === 429 || status >= 500) {
+                recordUpstreamStatus("provider.inference", "anthropic", status, {
+                    attempt,
+                    durationMs: now() - attemptStartedAt,
+                });
+            }
             // Routing state changes implied by the failure — cooldowns and sticky
             // binding invalidation — run before any retry decision, so the
             // re-acquisition below already sees the failed account excluded.
@@ -358,10 +418,16 @@ export function mountAnthropicMessagesRoute(app, opts) {
                     next?.release();
                     release();
                     upstream.destroy();
+                    endAttempt("cancelled", { httpStatusCode: status, streamOutcome: "cancelled" });
+                    settleRequest("cancelled", { httpStatusCode: status, streamOutcome: "cancelled", attempt });
                     return;
                 }
                 if (next) {
                     // Committed: record the failed attempt and abandon its response.
+                    endAttempt(status === 429 ? "rate_limited" : "upstream_error", {
+                        httpStatusCode: status,
+                        streamOutcome: "upstream_error",
+                    });
                     entry.details = `${entry.details}:will-retry`;
                     recordActivity(entry);
                     upstream.destroy();
@@ -404,6 +470,8 @@ export function mountAnthropicMessagesRoute(app, opts) {
                 recordActivity(entry);
                 upstream.destroy();
                 release();
+                endAttempt("cancelled", { httpStatusCode: status, streamOutcome: "cancelled" });
+                settleRequest("cancelled", { httpStatusCode: status, streamOutcome: "cancelled", attempt });
                 return;
             }
             // The held response can die while a retry decision is pending — its
@@ -421,6 +489,8 @@ export function mountAnthropicMessagesRoute(app, opts) {
                 entry.details = `${entry.details}:held-response-lost`;
                 recordActivity(entry);
                 release();
+                endAttempt("upstream_error", { httpStatusCode: 502, streamOutcome: "upstream_error" });
+                settleRequest("upstream_error", { httpStatusCode: 502, attempt });
                 logError(account.id, 502, `upstream ${status} response was lost before it could be relayed`);
                 res.status(502).json({
                     type: "error",
@@ -436,8 +506,77 @@ export function mountAnthropicMessagesRoute(app, opts) {
             // usage capture; the dashboard picks the values up on its next poll —
             // same contract as the generic proxy path.
             recordActivity(entry);
-            attachAnthropicResponseCapture(upstream, res, entry, startedAt);
-            relayUpstreamResponse(upstream, req, res);
+            const outcome = status === 429 ? "rate_limited"
+                : status >= 400 ? "upstream_error"
+                    : "complete";
+            annotateActiveSpan("proxy.request", {
+                httpStatusCode: status,
+                outcome,
+                attempt,
+                operationDurationMs: now() - startedAt,
+            });
+            // Tokens and the stream verdict are only known once the relayed body
+            // settles. The span waits for both the response's close and the passive
+            // usage capture (a compressed body decodes after close), bounded so a
+            // decoder that never finishes cannot keep the span open.
+            const contentType = String(upstream.headers["content-type"] ?? "");
+            const encoding = String(upstream.headers["content-encoding"] ?? "");
+            const isSse = contentType.includes("text/event-stream");
+            // Set by the relay when the provider connection failed first; a client
+            // hang-up also destroys the upstream, so the order of events matters.
+            let upstreamFailedFirst = false;
+            // The lifecycle tracker only reads uncompressed SSE; the usage capture's
+            // decoded copy reports the terminal event for compressed streams.
+            let decodedMessageStop = false;
+            let responseClosed = false;
+            let usageSettled = false;
+            let usageDeadline;
+            const finishAttempt = () => {
+                if (usageDeadline !== undefined)
+                    clearTimeout(usageDeadline);
+                const lifecycle = entry.streamLifecycle;
+                // A client hang-up destroys the upstream request too, so the client's
+                // own signal must win over the resulting upstream abort.
+                const streamOutcome = status >= 400 ? "upstream_error"
+                    : upstreamFailedFirst ? "upstream_error"
+                        : clientGone.signal.aborted ? "cancelled"
+                            : lifecycle?.upstreamAborted ? "upstream_error"
+                                : !res.writableEnded ? "cancelled"
+                                    : isSse && !lifecycle?.sawMessageStop && !decodedMessageStop ? "upstream_error"
+                                        : "complete";
+                const attemptOutcome = status >= 400 ? outcome
+                    : streamOutcome === "complete" ? outcome
+                        : streamOutcome;
+                const tokens = {
+                    ...(entry.inputTokens !== undefined ? { inputTokens: entry.inputTokens } : {}),
+                    ...(entry.outputTokens !== undefined ? { outputTokens: entry.outputTokens } : {}),
+                };
+                endAttempt(attemptOutcome, { httpStatusCode: status, streamOutcome, ...tokens });
+                settleRequest(attemptOutcome, { httpStatusCode: status, streamOutcome, attempt, ...tokens });
+            };
+            const maybeFinishAttempt = () => {
+                if (responseClosed && usageSettled)
+                    finishAttempt();
+            };
+            res.once("close", () => {
+                responseClosed = true;
+                if (!usageSettled) {
+                    usageDeadline = setTimeout(finishAttempt, USAGE_SETTLE_GRACE_MS);
+                    usageDeadline.unref?.();
+                }
+                maybeFinishAttempt();
+            });
+            attachAnthropicResponseCapture(upstream, res, entry, startedAt, {
+                onMessageStop: () => { decodedMessageStop = true; },
+                onUsageSettled: () => {
+                    usageSettled = true;
+                    maybeFinishAttempt();
+                },
+            });
+            relayUpstreamResponse(upstream, req, res, () => {
+                if (!clientGone.signal.aborted)
+                    upstreamFailedFirst = true;
+            });
             return;
         }
     };

package/dist/proxy/anthropic-proxy.js

@@ -1,4 +1,10 @@
 import { createProxyMiddleware } from "http-proxy-middleware";
+/**
+ * Inbound trace context is stripped rather than forwarded, by every Anthropic
+ * relay: telemetry never joins a client's distributed trace, and a client's
+ * context headers must not reach the upstream provider through this proxy.
+ */
+export const TRACE_CONTEXT_HEADERS = ["traceparent", "tracestate", "baggage"];
 /**
  * Construct the Anthropic transport with http-proxy-middleware's native
  * response piping. In particular, this deliberately does not self-handle,
@@ -15,6 +21,10 @@ export function createAnthropicProxy(options) {
         on: {
             ...options.on,
             proxyReq: (proxyRequest, request, response, proxyOptions) => {
+                // Telemetry never joins a distributed trace: a client's context headers
+                // must not reach the upstream provider through this proxy.
+                for (const header of TRACE_CONTEXT_HEADERS)
+                    proxyRequest.removeHeader(header);
                 proxyRequest.once("response", () => {
                     proxyRequest.setTimeout(0);
                     request.socket.setTimeout(0);

package/dist/proxy/anthropic-response-capture.js

@@ -1,25 +1,7 @@
 import { applyAnthropicInputUsage, applyAnthropicOutputUsage } from "./stats.js";
 import { createAnthropicUsageCapture } from "./usage-capture.js";
 import { createStreamLifecycleTracker } from "./stream-lifecycle.js";
-/**
- * Attach the passive observability taps to a relayed Anthropic response:
- * stream-lifecycle tracking and token-usage capture, both mutating the
- * already-recorded activity entry in place (the dashboard picks the values
- * up on its next poll).
- *
- * SSE streams carry usage across two events (message_start → input/cache
- * tokens, message_delta → output tokens); non-streaming JSON carries all
- * fields in one usage object. The proxy is byte-transparent and the client's
- * accept-encoding makes upstream compress, so the capture decompresses its
- * own copy of the stream (see usage-capture.ts) — previously compressed
- * responses were skipped, which in practice was EVERY response.
- *
- * Shared by the generic /v1 proxy and the retrying /v1/messages transport so
- * the two Anthropic relays can never drift on what they observe. Must run
- * BEFORE the response is piped to the client, in the same synchronous block,
- * so no data event can slip past the taps.
- */
-export function attachAnthropicResponseCapture(upstream, downstream, entry, startedAt) {
+export function attachAnthropicResponseCapture(upstream, downstream, entry, startedAt, hooks = {}) {
     const contentType = String(upstream.headers["content-type"] ?? "");
     const encoding = String(upstream.headers["content-encoding"] ?? "");
     const isCompressed = /gzip|br|deflate/.test(encoding);
@@ -32,9 +14,14 @@ export function attachAnthropicResponseCapture(upstream, downstream, entry, star
         contentEncoding: encoding,
         onInputUsage: usage => applyAnthropicInputUsage(entry, usage),
         onOutputUsage: usage => applyAnthropicOutputUsage(entry, usage),
+        onSettled: () => hooks.onUsageSettled?.(),
+        ...(hooks.onMessageStop ? { onMessageStop: hooks.onMessageStop } : {}),
     });
     if (usageCapture) {
         upstream.on("data", (chunk) => usageCapture.write(chunk));
         upstream.on("end", () => usageCapture.end());
     }
+    else {
+        hooks.onUsageSettled?.();
+    }
 }

package/dist/proxy/openai-ingress.js

@@ -7,6 +7,7 @@ import { logError, logRoute } from "./logger.js";
 import { EmptyPoolError, NoEligibleAccountError } from "./account-pool.js";
 import { acquireRequestRoute, routeReasonDetails, routeFailureDetails } from "./lease-lifecycle.js";
 import { createCorrelationId, formatTransportDiagnostic, safeCauseCode } from "./transport-diagnostics.js";
+import { annotateActiveSpan, modelFamilyOf, recordRuntimeError, recordUpstreamStatus, settleProxyRequestSpan, startTelemetrySpan, } from "../telemetry/facade.js";
 import { MAX_UPSTREAM_ATTEMPTS, RETRY_REFRESH_TIMEOUT_MS, SAME_ACCOUNT_RETRY_DELAY_MS, boundedWait, isRetryableUpstreamStatus, retryDelay, } from "./upstream-retry.js";
 /**
  * Mirrors `anthropic-routing.ts`'s `requestTerminated` check. This ingress
@@ -91,6 +92,16 @@ export function mirrorUpstreamHeaders(source, apply) {
         apply(key, value);
     });
 }
+/** Map the activity-log client label onto the closed telemetry request source. */
+function requestSourceOf(source) {
+    switch (source) {
+        case "codex":
+        case "cli": return "cli";
+        case "desktop": return "desktop";
+        case "api": return "api";
+        default: return "other";
+    }
+}
 /**
  * Shared OpenAI/Codex ingress lifecycle: acquire a sticky account lease,
  * refresh its token if needed, forward the request, classify the upstream
@@ -109,6 +120,18 @@ export async function runOpenAIIngress(opts) {
     // it still carries whatever model the caller asked for.
     const requestedModel = boundModelId(opts.requestedModel);
     const correlationId = createCorrelationId();
+    const route = path === "/v1/messages" ? "messages" : "responses";
+    const modelFamily = modelFamilyOf(requestedModel);
+    const streaming = forwardBody.stream === true;
+    const telemetryStartedAt = now();
+    annotateActiveSpan("proxy.request", {
+        provider: "openai",
+        route,
+        modelFamily,
+        requestSource: opts.requestSource ?? requestSourceOf(opts.source),
+        streaming,
+        accountPoolSize: openAIPool.getAll().length,
+    });
     // A client that hangs up must take the upstream request with it. Releasing
     // the lease (which the response's own close listener does) only returns the
     // account's *local* capacity — without this the Codex request keeps
@@ -259,9 +282,30 @@ export async function runOpenAIIngress(opts) {
     let upstreamFailed;
     let details;
     let accountFailureCounted;
+    let attemptSpan;
+    let attemptStartedAt = now();
+    let attemptCount = 0;
+    /** Close the attempt's span exactly once, on the outcome it ended with. */
+    const endAttemptSpan = (outcome, extra = {}) => {
+        attemptSpan?.annotate({
+            ...extra,
+            outcome,
+            attempt: attemptCount,
+            operationDurationMs: now() - attemptStartedAt,
+        });
+        attemptSpan?.end(outcome === "complete" ? "ok" : "error");
+    };
     for (let attempt = 1;; attempt++) {
         const account = selected.route.account;
-        const attemptStartedAt = now();
+        attemptStartedAt = now();
+        attemptCount = attempt;
+        attemptSpan = startTelemetrySpan("provider.inference", {
+            provider: "openai",
+            route,
+            modelFamily,
+            streaming,
+            attempt,
+        });
         try {
             upstream = await forwardOpenAI({
                 account,
@@ -281,6 +325,7 @@ export async function runOpenAIIngress(opts) {
             // pre-forward disconnect branch above, which also just releases and stops.
             if (clientGone.signal.aborted || responseTerminated(res)) {
                 selected.release();
+                endAttemptSpan("cancelled", { streamOutcome: "cancelled" });
                 return;
             }
             // A rejected forward call (network failure) must produce a local 502,
@@ -307,9 +352,30 @@ export async function runOpenAIIngress(opts) {
                 headerDurationMs: now() - attemptStartedAt,
             });
             res.status(timeout ? 504 : 502).json(envelope.wrap("upstream_error", timeout ? "OpenAI request timed out" : "OpenAI request failed"));
+            recordRuntimeError(error, { operation: "provider.inference", provider: "openai" }, {
+                attempt,
+                durationMs: now() - attemptStartedAt,
+            });
+            endAttemptSpan(timeout ? "timeout" : "upstream_error", {
+                httpStatusCode: timeout ? 504 : 502,
+                streamOutcome: timeout ? "timeout" : "upstream_error",
+            });
+            settleProxyRequestSpan(res, {
+                httpStatusCode: timeout ? 504 : 502,
+                outcome: timeout ? "timeout" : "upstream_error",
+                attempt,
+                operationDurationMs: now() - telemetryStartedAt,
+            });
             return;
         }
         headerDurationMs = now() - attemptStartedAt;
+        if (upstream.status === 401 || upstream.status === 403
+            || upstream.status === 429 || upstream.status >= 500) {
+            recordUpstreamStatus("provider.inference", "openai", upstream.status, {
+                attempt,
+                durationMs: headerDurationMs,
+            });
+        }
         // Cooldown/eligibility react to the raw upstream signal — this must not
         // change based on how the relay later renders the response to the client.
         upstreamFailed = upstream.status === 401 || upstream.status === 429 || upstream.status >= 500;
@@ -402,6 +468,10 @@ export async function runOpenAIIngress(opts) {
         if (!prepared)
             break;
         // Committed: record the failed attempt and abandon its response.
+        endAttemptSpan(upstream.status === 429 ? "rate_limited" : "upstream_error", {
+            httpStatusCode: upstream.status,
+            streamOutcome: "upstream_error",
+        });
         stats.totalErrors++;
         recordActivity({
             ts: attemptStartedAt,
@@ -428,6 +498,12 @@ export async function runOpenAIIngress(opts) {
             await retryDelay(sameAccountDelayMs, clientGone.signal);
         if (clientGone.signal.aborted || responseTerminated(res)) {
             selected.release();
+            settleProxyRequestSpan(res, {
+                outcome: "cancelled",
+                streamOutcome: "cancelled",
+                attempt,
+                operationDurationMs: now() - telemetryStartedAt,
+            });
             return;
         }
     }
@@ -546,4 +622,25 @@ export async function runOpenAIIngress(opts) {
     entry.statusCode = finalStatus;
     entry.durationMs = now() - startedAt;
     recordActivity(entry);
+    const outcome = clientCancelled ? "cancelled"
+        : finalStatus === 429 ? "rate_limited"
+            : failedFinal ? "upstream_error"
+                : "complete";
+    const streamOutcome = clientCancelled ? "cancelled"
+        : failedFinal ? "upstream_error"
+            : "complete";
+    const tokens = {
+        ...(entry.inputTokens !== undefined ? { inputTokens: entry.inputTokens } : {}),
+        ...(entry.outputTokens !== undefined ? { outputTokens: entry.outputTokens } : {}),
+    };
+    attemptSpan?.annotate(tokens);
+    endAttemptSpan(outcome, { httpStatusCode: finalStatus, streamOutcome });
+    settleProxyRequestSpan(res, {
+        ...tokens,
+        httpStatusCode: finalStatus,
+        outcome,
+        streamOutcome,
+        attempt: attemptCount,
+        operationDurationMs: now() - telemetryStartedAt,
+    });
 }

package/dist/proxy/server.js

@@ -9,8 +9,8 @@ import { needsRefresh, refreshAccountIfCurrent, refreshAccountsOnce, saveAccount
 import { loadAccounts, loadOpenAIAccounts, saveOpenAIAccountsToPath, accountsFileExists, readAccountsFromPath, readConfig, writeConfig, getAutoFailoverEnabled, getProxyRequestTimeoutMs, migrateLegacyAccountProviders, setProviderAccountsEnabled, upsertAccountRecord, removeAccountRecordById } from "../config/manager.js";
 import { createRefreshAllRunner, describeRefreshAll, refreshAllAccounts } from "./pool-refresh.js";
 import { checkForUpdate, performUpdate, restartSelf, printUpdateBanner, getCurrentVersion } from "../utils/self-update.js";
-import { trackEvent, startHeartbeat } from "../utils/telemetry.js";
-import { loadTelemetryState } from "../config/telemetry.js";
+import { annotateActiveSpan, httpOutcome, modelFamilyOf, recordProxyStarted, runtimeMode, shutdownTelemetryWithin, startProxyHeartbeat, telemetryRequestMiddleware, } from "../telemetry/facade.js";
+import { startTelemetryRuntime } from "../telemetry/runtime.js";
 import { logRoute, logError, logStartup } from "./logger.js";
 import { createLocalRoutingErrorLog, stats } from "./stats.js";
 import { applyRateLimitHeaders } from "../providers/anthropic/rate-limit-headers.js";
@@ -40,6 +40,8 @@ import { accountDeletionStatusCode, deleteAnthropicAccountTransaction, deleteOpe
 import { addOpenAIAccountTransaction } from "./account-add.js";
 import { createAnthropicRefreshMiddleware, createAnthropicRoutingMiddleware, } from "./anthropic-routing.js";
 import { createAllowanceView } from "./allowance.js";
+/** Upper bound on how long a shutdown may wait for telemetry to drain. */
+const TELEMETRY_SHUTDOWN_DEADLINE_MS = 1_000;
 const zeroRoutingMetrics = () => ({
     inFlightRequests: 0,
     activeSessions: 0,
@@ -334,6 +336,9 @@ export function createOpenAIPersister(accountsPath) {
     };
 }
 export async function startServer(opts = {}) {
+    // Best effort and non-throwing: a telemetry runtime that cannot start just
+    // leaves every later facade call inert.
+    startTelemetryRuntime({ tracing: true, runtimeMode: runtimeMode() });
     const port = opts.port ?? PROXY_PORT;
     // Direct-to-Anthropic (standalone) or via LiteLLM (full mode).
     // Priority: explicit option > LITELLM_URL env var > direct to Anthropic
@@ -1049,6 +1054,9 @@ export async function startServer(opts = {}) {
     const onOpenAIUpstreamAuthFailure = (account) => {
         refreshAndPersistOpenAIAccount(account, openAIAccounts, persistOpenAIAccounts).catch(() => { });
     };
+    // Wraps only /v1/messages and /v1/responses in a server span; every other
+    // route passes straight through.
+    app.use(telemetryRequestMiddleware());
     mountResponsesRoutes(app, {
         openAIRouter,
         openAIPool,
@@ -1160,6 +1168,11 @@ export async function startServer(opts = {}) {
                 const durationMs = req._startTime
                     ? Date.now() - req._startTime
                     : undefined;
+                annotateActiveSpan("proxy.request", {
+                    httpStatusCode: status,
+                    outcome: httpOutcome(status),
+                    ...(durationMs !== undefined ? { operationDurationMs: durationMs } : {}),
+                });
                 // Complete the pending log entry with response info
                 const pendingLog = req._pendingLog ?? {
                     ts: Date.now(),
@@ -1296,6 +1309,14 @@ export async function startServer(opts = {}) {
             : req.headers["x-api-key"]
                 ? "desktop"
                 : "api";
+        annotateActiveSpan("proxy.request", {
+            provider: "anthropic",
+            route: "messages",
+            modelFamily: modelFamilyOf(req._ccRouteContext?.requestedModel ?? "-"),
+            requestSource: source,
+            accountPoolSize: pool.getAll().length,
+            concurrency: pool.getInFlight(account.id),
+        });
         req._pendingLog = {
             ts: Date.now(),
             accountId: account.id,
@@ -1316,7 +1337,13 @@ export async function startServer(opts = {}) {
         changeOrigin: true,
     }));
     // ─── Graceful shutdown ────────────────────────────────────────────────────
-    const shutdown = () => {
+    let shuttingDown = false;
+    const shutdown = async () => {
+        // A second signal while the bounded telemetry flush runs must not repeat
+        // the persistence work below.
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         console.log(chalk.yellow("\nShutting down — saving tokens..."));
         usageRefresher.stop();
         openAIUsageRefresher.stop();
@@ -1324,10 +1351,11 @@ export async function startServer(opts = {}) {
         if (managesPidFile()) {
             removePid();
         }
+        await shutdownTelemetryWithin(TELEMETRY_SHUTDOWN_DEADLINE_MS);
         process.exit(0);
     };
-    process.on("SIGTERM", shutdown);
-    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", () => { void shutdown(); });
+    process.on("SIGINT", () => { void shutdown(); });
     // ─── Update handling ──────────────────────────────────────────────────────
     // Auto-update is OFF by default: installing code unattended from the npm
     // registry (no signature/provenance check) turns any publish-channel
@@ -1402,22 +1430,7 @@ export async function startServer(opts = {}) {
         console.log(autoFailover
             ? chalk.gray("  Auto-failover: on — 429/5xx retried across accounts before the first relayed byte")
             : chalk.gray("  Auto-failover: off — upstream failures pass through; clients own retries"));
-        // Anonymous telemetry — fire-and-forget, never blocks proxy startup.
-        try {
-            const telemetryState = loadTelemetryState();
-            // First-run detection: if the install is brand new, emit app_started too
-            const firstRunAge = Date.now() - new Date(telemetryState.firstRunAt).getTime();
-            if (firstRunAge < 5 * 60 * 1000) {
-                void trackEvent("app_started", { first_run: true });
-            }
-            void trackEvent("proxy_started", {
-                account_count: totalAccountCount,
-                mode,
-            });
-            startHeartbeat(totalAccountCount);
-        }
-        catch {
-            // never let telemetry break the proxy
-        }
+        recordProxyStarted(totalAccountCount);
+        startProxyHeartbeat(() => pool.getAll().length + openAIPool.getAll().length);
     });
 }