@juspay/neurolink 12.14.6 → 12.14.7

package/dist/cli/commands/proxy.js

@@ -12,6 +12,7 @@ import { applyAllClients, restoreAllClients, } from "../proxy-clients/registry.j
 import { resolveProxyConfigPath } from "../../proxy/proxyConfig.js";
 import { redactUrlsInText, sanitizeForLog, } from "../../utils/logSanitize.js";
 import { withTimeout } from "../../utils/async/withTimeout.js";
+import { startProxyHttpTrace } from "../../proxy/proxyTracer.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
 import { configureProxyKeepAliveDispatcher } from "../../proxy/proxyDispatcher.js";
 import { ProxyRuntimeConfigStore } from "../../proxy/runtimeConfig.js";
@@ -837,13 +838,36 @@ function spawnProxyUpdater(host, port, parentPid, rollingSupervisor = false) {
         workerLog.close();
     }
 }
-async function runProxyTelemetryManager(command) {
+async function runProxyTelemetryManager(command, argv) {
     const { existsSync } = await import("fs");
     if (!existsSync(PROXY_TELEMETRY_SCRIPT_PATH)) {
         throw new Error("Proxy telemetry helper files were not found in this installation. Reinstall NeuroLink with observability assets included.");
     }
     await new Promise((resolve, reject) => {
-        const child = spawn("bash", [PROXY_TELEMETRY_SCRIPT_PATH, command], {
+        const queryCommand = command === "doctor" || command === "query";
+        const queryArgs = [];
+        if (queryCommand && argv) {
+            for (const [key, option] of [
+                ["since", "--since"],
+                ["until", "--until"],
+                ["kind", "--kind"],
+                ["format", "--format"],
+                ["maxRows", "--max-rows"],
+                ["proxyUrl", "--proxy-url"],
+            ]) {
+                if (argv[key] !== undefined) {
+                    queryArgs.push(option, String(argv[key]));
+                }
+            }
+        }
+        const child = spawn(queryCommand ? process.execPath : "bash", queryCommand
+            ? [
+                join(dirname(PROXY_TELEMETRY_SCRIPT_PATH), command === "doctor"
+                    ? "check-proxy-telemetry.mjs"
+                    : "query-proxy-history.mjs"),
+                ...queryArgs,
+            ]
+            : [PROXY_TELEMETRY_SCRIPT_PATH, command], {
             stdio: "inherit",
             env: process.env,
         });
@@ -1078,6 +1102,7 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
             rejectForUpdate: readiness.drainingForUpdate,
         };
         requestMetadata.set(c.req.raw, metadata);
+        const httpTrace = startProxyHttpTrace(metadata, Object.fromEntries(c.req.raw.headers));
         const stopObservingFinalLog = observeProxyFinalLog(metadata.requestId, (entry) => {
             metadata.terminalResult = entry;
         }, (entry) => {
@@ -1087,6 +1112,7 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
             ? () => undefined
             : beginProxyRequest();
         const finish = () => {
+            httpTrace.end(metadata.terminalResult?.responseStatus ?? c.res.status, metadata.terminalResult?.terminalOutcome ?? "unknown", metadata.terminalErrorType);
             stopObservingFinalLog();
             finishActivity();
             // Borrowed traffic holds a concurrency slot for the lifetime of the
@@ -1099,7 +1125,7 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
         // them at acceptance instead of publishing misleading placeholder values;
         // subsequent events carry the parsed metadata under the same request ID.
         try {
-            await persistProxyLifecycleAcceptance({
+            await httpTrace.run(() => persistProxyLifecycleAcceptance({
                 requestId: metadata.requestId,
                 method: metadata.method,
                 path: metadata.path,
@@ -1107,8 +1133,8 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                 requestBytes,
                 elapsedMs: 0,
                 monotonicMs: startedMonotonicMs,
-            });
-            await next();
+            }));
+            await httpTrace.run(next);
             const responseStatus = c.res.status;
             logProxyLifecycleEvent({
                 event: "response_headers",
@@ -1169,12 +1195,12 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                     let accountingTimedOut = false;
                     let accountingFailed = false;
                     try {
-                        accountingFailed = await notifyRouteTerminal({
+                        accountingFailed = await httpTrace.run(() => notifyRouteTerminal({
                             outcome,
                             error,
                             observedBodyBytes,
                             responseChunks,
-                        });
+                        }));
                     }
                     catch {
                         accountingTimedOut = true;
@@ -1231,6 +1257,7 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                         errorCode: final?.errorCode ?? metadata.terminalErrorCode,
                     });
                     stopObservingFinalLog();
+                    httpTrace.end(final?.responseStatus ?? responseStatus, terminalOutcome, final?.errorType ?? metadata.terminalErrorType);
                 },
             });
         }
@@ -1259,6 +1286,9 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                 errorType: error instanceof Error ? error.name : "unknown_error",
                 errorCode: getProxyRuntimeErrorCode(error),
             });
+            httpTrace.end(getProxyRuntimeErrorCode(error) === "PROXY_TELEMETRY_UNAVAILABLE"
+                ? 503
+                : 502, "handler_error", error instanceof Error ? error.name : "unknown_error");
             throw error;
         }
     };
@@ -1331,8 +1361,9 @@ export async function createProxyStartApp(params) {
                 accountKey: attempt?.accountKey,
                 provider: attempt?.provider,
                 transportScope: attempt?.transportScope,
-                traceId: attempt?.traceId,
-                spanId: attempt?.spanId,
+                traceId: attempt?.traceId ?? metadata.traceId,
+                spanId: attempt?.spanId ?? metadata.spanId,
+                traceFlags: attempt?.traceFlags ?? metadata.traceFlags,
                 responseStatus: status,
                 responseTimeMs: Date.now() - metadata.startedAt,
                 errorType,
@@ -1342,6 +1373,9 @@ export async function createProxyStartApp(params) {
             logBodyCapture({
                 timestamp: new Date().toISOString(),
                 requestId: metadata.requestId,
+                traceId: attempt?.traceId ?? metadata.traceId,
+                spanId: attempt?.spanId ?? metadata.spanId,
+                traceFlags: attempt?.traceFlags ?? metadata.traceFlags,
                 model: metadata.model,
                 stream: metadata.stream,
                 phase: "client_response",
@@ -3553,6 +3587,8 @@ export const proxyStatusCommand = {
 // PROXY TELEMETRY COMMAND
 // =============================================================================
 const PROXY_TELEMETRY_ACTIONS = [
+    "doctor",
+    "query",
     "setup",
     "start",
     "stop",
@@ -3562,12 +3598,37 @@ const PROXY_TELEMETRY_ACTIONS = [
 ];
 export const proxyTelemetryCommand = {
     command: "telemetry <action>",
-    describe: "Manage the local OpenObserve stack and dashboard for proxy observability",
+    describe: "Query and verify stored OTel telemetry or manage the local observability stack",
     builder: (yargs) => yargs
         .positional("action", {
         type: "string",
         choices: [...PROXY_TELEMETRY_ACTIONS],
-        describe: "Telemetry action: setup, start, stop, status, logs, or import-dashboard",
+        describe: "Telemetry action: doctor, query, setup, start, stop, status, logs, or import-dashboard",
+    })
+        .option("since", {
+        type: "string",
+        description: "Inclusive ISO timestamp for stored telemetry",
+    })
+        .option("until", {
+        type: "string",
+        description: "Exclusive ISO timestamp for stored telemetry",
+    })
+        .option("kind", {
+        type: "string",
+        description: "Metadata kind for query, such as request_final or telemetry_delivery",
+    })
+        .option("format", {
+        type: "string",
+        choices: ["json", "text"],
+        description: "Doctor report format; query always returns JSON",
+    })
+        .option("max-rows", {
+        type: "number",
+        description: "Explicit bounded history record limit",
+    })
+        .option("proxy-url", {
+        type: "string",
+        description: "Proxy endpoint used by the read-only doctor",
     })
         .option("quiet", {
         type: "boolean",
@@ -3575,19 +3636,21 @@ export const proxyTelemetryCommand = {
         default: false,
         description: "Suppress the local CLI spinner and delegate directly",
     })
+        .example("neurolink proxy telemetry doctor --format json", "Verify field coverage, stored captures, trace correlation, and delivery evidence")
+        .example("neurolink proxy telemetry query --since 2026-09-15T00:00:00Z --kind request_final", "Read stored OTLP metadata without scanning proxy log files")
         .example("neurolink proxy telemetry setup", "Start OpenObserve, start the OTEL collector, and import the dashboard")
         .example("neurolink proxy telemetry start", "Start the local proxy telemetry stack without re-importing the dashboard")
         .example("neurolink proxy telemetry stop", "Stop the local OpenObserve and OTEL collector containers"),
     handler: async (argv) => {
         const action = argv.action;
-        const spinner = argv.quiet
+        const spinner = argv.quiet || action === "doctor" || action === "query"
             ? null
             : ora(`Running proxy telemetry ${action}...`).start();
         try {
             if (spinner) {
                 spinner.stop();
             }
-            await runProxyTelemetryManager(action);
+            await runProxyTelemetryManager(action, argv);
             if (spinner) {
                 spinner.succeed(`proxy telemetry ${action} completed`);
             }

package/dist/proxy/bodyCaptureWorker.js

@@ -18,6 +18,8 @@ const snapshot = {
     pendingBytes: 0,
     maxPending: MAX_PENDING,
     maxPendingBytes: MAX_PENDING_BYTES,
+    highWaterPending: 0,
+    highWaterBytes: 0,
     rejectionReasons: {},
 };
 const pending = new Map();
@@ -161,9 +163,27 @@ export async function captureProxyBody(entry, logDir, consume) {
                 ? "body_worker_backoff"
                 : "body_capture_queue_full";
         snapshot.lastError = error;
+        snapshot.lastRejectedAt = new Date().toISOString();
         snapshot.rejectionReasons[error] =
             (snapshot.rejectionReasons[error] ?? 0) + 1;
-        return consume({ error, stored: { bodyWriteFailed: true } });
+        return consume({
+            error,
+            stored: { bodyWriteFailed: true },
+            admission: {
+                limitingResource: bytes > MAX_ENTRY_BYTES
+                    ? "entry"
+                    : Date.now() < retryAfter
+                        ? "worker"
+                        : snapshot.pending >= MAX_PENDING
+                            ? "captures"
+                            : "bytes",
+                estimatedBytes: Number.isFinite(bytes) ? bytes : undefined,
+                pending: snapshot.pending,
+                pendingBytes: snapshot.pendingBytes,
+                maxPending: MAX_PENDING,
+                maxPendingBytes: MAX_PENDING_BYTES,
+            },
+        });
     }
     let current;
     try {
@@ -207,7 +227,9 @@ export async function captureProxyBody(entry, logDir, consume) {
             },
         });
         snapshot.pending += 1;
+        snapshot.highWaterPending = Math.max(snapshot.highWaterPending, snapshot.pending);
         snapshot.pendingBytes += bytes;
+        snapshot.highWaterBytes = Math.max(snapshot.highWaterBytes, snapshot.pendingBytes);
         current.ref();
         try {
             current.postMessage({ id, entry, logDir, queuedAt: Date.now() });
@@ -248,6 +270,9 @@ export const __bodyCaptureWorkerTestHooks = {
             pending: 0,
             pendingBytes: 0,
             lastError: undefined,
+            lastRejectedAt: undefined,
+            highWaterPending: 0,
+            highWaterBytes: 0,
             rejectionReasons: {},
         });
     },

package/dist/proxy/codexUsage.js

@@ -45,6 +45,34 @@ import { sanitizeForLog } from "../utils/logSanitize.js";
 const nonNegativeInt = (value) => typeof value === "number" && Number.isFinite(value) && value > 0
     ? Math.floor(value)
     : 0;
+function usefulOutputItem(item) {
+    if (!item || typeof item !== "object") {
+        return false;
+    }
+    if ("type" in item) {
+        if (item.type === "function_call") {
+            return ("arguments" in item &&
+                typeof item.arguments === "string" &&
+                item.arguments.length > 0);
+        }
+        if (item.type === "custom_tool_call") {
+            return ("input" in item &&
+                typeof item.input === "string" &&
+                item.input.length > 0);
+        }
+        if (item.type === "output_text") {
+            return ("text" in item && typeof item.text === "string" && item.text.length > 0);
+        }
+        if (item.type === "refusal") {
+            return ("refusal" in item &&
+                typeof item.refusal === "string" &&
+                item.refusal.length > 0);
+        }
+    }
+    return ("content" in item &&
+        Array.isArray(item.content) &&
+        item.content.some(usefulOutputItem));
+}
 /**
  * Pull usage out of one parsed SSE `data:` payload.
  *
@@ -125,7 +153,7 @@ const CAPTURE_LIMIT_BYTES = 256 * 1024;
  */
 function createCaptureSink() {
     const target = process.env.NEUROLINK_PROXY_CODEX_CAPTURE;
-    if (!target) {
+    if (!target || process.env.NEUROLINK_PROXY_LOG_SINK === "otel") {
         return null;
     }
     let written = 0;
@@ -167,9 +195,13 @@ export function createCodexUsageTap() {
     let totalBytes = 0;
     const inspectEvidence = (events) => {
         for (const frame of events) {
+            if (frame.data.trim() === "[DONE]") {
+                continue;
+            }
             try {
                 const event = JSON.parse(frame.data);
                 if (!event || typeof event !== "object") {
+                    evidence.observationIncomplete = true;
                     continue;
                 }
                 const seen = extractCodexUsage(event);
@@ -178,10 +210,53 @@ export function createCodexUsageTap() {
                 }
                 const type = event.type ?? frame.event;
                 if ((type === "response.output_text.delta" ||
+                    type === "response.refusal.delta" ||
                     type === "response.function_call_arguments.delta") &&
                     typeof event.delta === "string" &&
                     event.delta.length > 0) {
-                    evidence.firstUsefulOutputAt ??= Date.now();
+                    if (evidence.firstUsefulOutputAt === undefined) {
+                        evidence.firstUsefulOutputAt = Date.now();
+                        evidence.firstUsefulOutputEvent = String(type);
+                    }
+                }
+                // Some clients/providers emit complete output items without deltas.
+                // Reasoning/control events are not useful client output. Recognize
+                // actual tool calls and text only, without inventing an earlier time.
+                const usefulItem = usefulOutputItem(event.item);
+                const completedResponse = event.response;
+                const usefulCompletion = type === "response.completed" &&
+                    completedResponse &&
+                    typeof completedResponse === "object" &&
+                    "output" in completedResponse &&
+                    Array.isArray(completedResponse.output) &&
+                    completedResponse.output.some(usefulOutputItem);
+                const usefulDone = (type === "response.output_text.done" &&
+                    typeof event.text === "string" &&
+                    event.text.length > 0) ||
+                    (type === "response.refusal.done" &&
+                        typeof event.refusal === "string" &&
+                        event.refusal.length > 0) ||
+                    (type === "response.function_call_arguments.done" &&
+                        typeof event.arguments === "string" &&
+                        event.arguments.length > 0) ||
+                    (type === "response.custom_tool_call_input.done" &&
+                        typeof event.input === "string" &&
+                        event.input.length > 0) ||
+                    ((type === "response.content_part.added" ||
+                        type === "response.content_part.done") &&
+                        usefulOutputItem(event.part));
+                const usefulToolDelta = type === "response.custom_tool_call_input.delta" &&
+                    typeof event.delta === "string" &&
+                    event.delta.length > 0;
+                if (evidence.firstUsefulOutputAt === undefined &&
+                    (usefulDone ||
+                        usefulCompletion ||
+                        usefulToolDelta ||
+                        ((type === "response.output_item.added" ||
+                            type === "response.output_item.done") &&
+                            usefulItem))) {
+                    evidence.firstUsefulOutputAt = Date.now();
+                    evidence.firstUsefulOutputEvent = String(type);
                 }
                 if (type === "response.completed") {
                     evidence.completed = true;
@@ -222,6 +297,7 @@ export function createCodexUsageTap() {
             }
             catch {
                 // Unknown frames cannot establish successful completion.
+                evidence.observationIncomplete = true;
             }
         }
     };
@@ -268,16 +344,21 @@ export function createCodexUsageTap() {
                 carry = remainder;
                 inspectEvidence(events);
                 if (carry.length > CARRY_LIMIT_CHARS) {
+                    evidence.observationIncomplete = true;
                     carry = carry.slice(-2);
                     discardingEvent = true;
                 }
             }
             catch {
                 // Telemetry must never break the relay.
+                evidence.observationIncomplete = true;
             }
         },
         flush() {
             // An event without its dispatch delimiter is incomplete on the wire.
+            if (discardingEvent || carry.trim()) {
+                evidence.observationIncomplete = true;
+            }
             settle(latest);
         },
         /**

package/dist/proxy/otelLogSink.d.ts

@@ -34,6 +34,18 @@ export declare function getProxyOtelLogSnapshot(): {
         maxPendingBytes: number;
     };
     queues: {
+        recentFailures: {
+            records: {
+                eventId: string;
+                kind?: string;
+                requestId?: string;
+                captureId?: string;
+            }[];
+            id: string;
+            at: string;
+            reason: "export_unconfirmed" | "queue_full";
+            error?: string;
+        }[];
         attempted: number;
         submitted: number;
         transportAcknowledged: number;
@@ -43,6 +55,7 @@ export declare function getProxyOtelLogSnapshot(): {
         lastAcknowledgedAt: string | undefined;
         lastFailureAt: string | undefined;
         highWaterOutstanding: number;
+        failureHistoryEvicted: number;
         kind: "metadata" | "bodies";
         capacity: number;
     }[];

package/dist/proxy/otelLogSink.js

@@ -1,5 +1,7 @@
 /* eslint-disable no-console -- This proxy-only sink replaces console methods with OTLP emission. */
 import { inspect } from "node:util";
+import { randomUUID } from "node:crypto";
+import { getProxyRequestTraceContext, proxyLogContext, } from "./proxyTraceContext.js";
 import { setImmediate as yieldToRequests } from "node:timers/promises";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 import { ExportResultCode } from "@opentelemetry/core";
@@ -45,6 +47,52 @@ function createTrackedProcessor(url, capacity, kind) {
         lastAcknowledgedAt: undefined,
         lastFailureAt: undefined,
         highWaterOutstanding: 0,
+        recentFailures: [],
+        failureHistoryEvicted: 0,
+    };
+    const diagnostics = [];
+    let diagnosticScheduled = false;
+    const rememberFailure = (records, reason, error) => {
+        const stringAttribute = (record, name) => {
+            const value = record.attributes[name];
+            return typeof value === "string" ? value.slice(0, 128) : undefined;
+        };
+        const failure = {
+            id: randomUUID(),
+            at: new Date().toISOString(),
+            reason,
+            ...(error ? { error: sanitizeForLog(error.message).slice(0, 256) } : {}),
+            records: records.slice(0, 64).map((record) => ({
+                eventId: stringAttribute(record, "proxy.event_id") ?? "unavailable",
+                kind: stringAttribute(record, "proxy.record_kind"),
+                requestId: stringAttribute(record, "request.id"),
+                captureId: stringAttribute(record, "body.capture_id"),
+            })),
+        };
+        if (state.recentFailures.length === 16) {
+            state.recentFailures.shift();
+            state.failureHistoryEvicted++;
+        }
+        state.recentFailures.push(failure);
+        // A failed diagnostic must not generate another diagnostic recursively.
+        if (records.some((record) => record.attributes["proxy.record_kind"] !== "telemetry_delivery")) {
+            if (diagnostics.length === 16) {
+                diagnostics.shift();
+            }
+            diagnostics.push(failure);
+        }
+    };
+    const publishRecoveredDiagnostics = () => {
+        if (diagnosticScheduled || !diagnostics.length || shuttingDown) {
+            return;
+        }
+        diagnosticScheduled = true;
+        queueMicrotask(() => {
+            diagnosticScheduled = false;
+            for (const failure of diagnostics.splice(0)) {
+                emitProxyOtelEvent("telemetry_delivery", { queue: kind, ...failure });
+            }
+        });
     };
     const transport = new OTLPLogExporter({ url, timeoutMillis: 5000 });
     const exporter = {
@@ -65,10 +113,12 @@ function createTrackedProcessor(url, capacity, kind) {
                 if (result.code === ExportResultCode.SUCCESS) {
                     state.transportAcknowledged += records.length;
                     state.lastAcknowledgedAt = new Date().toISOString();
+                    publishRecoveredDiagnostics();
                 }
                 else {
                     state.exportUnconfirmed += records.length;
                     state.lastFailureAt = new Date().toISOString();
+                    rememberFailure(records, "export_unconfirmed", result.error);
                 }
                 for (const record of records) {
                     unsettled.delete(record);
@@ -109,6 +159,7 @@ function createTrackedProcessor(url, capacity, kind) {
     });
     const processor = {
         onEmit(record) {
+            record.attributes["proxy.event_id"] ??= randomUUID();
             state.attempted++;
             const id = record.attributes?.["body.capture_id"];
             const publication = typeof id === "string" ? bodyPublications.get(id) : undefined;
@@ -117,6 +168,7 @@ function createTrackedProcessor(url, capacity, kind) {
             }
             if (state.outstanding >= capacity) {
                 state.dropped++;
+                rememberFailure([record], "queue_full");
                 if (publication) {
                     publication.dropped++;
                     publication.notify?.();
@@ -355,12 +407,17 @@ export function emitProxyOtelEvent(kind, record) {
         return;
     }
     try {
+        const ids = typeof record.requestId === "string" && !record.traceId
+            ? getProxyRequestTraceContext(record.requestId)
+            : undefined;
+        const correlated = ids ? { ...record, ...ids } : record;
         initializeProxyOtelLogs()
             ?.getLogger("neurolink-proxy-events")
             .emit({
+            context: proxyLogContext(correlated),
             severityNumber: SeverityNumber.INFO,
             severityText: "INFO",
-            body: JSON.stringify(record),
+            body: JSON.stringify(correlated),
             attributes: {
                 "proxy.record_kind": kind,
                 "event.name": `proxy.${kind}`,
@@ -444,6 +501,10 @@ export function getProxyOtelLogSnapshot() {
             kind: q.kind,
             capacity: q.capacity,
             ...q.state,
+            recentFailures: q.state.recentFailures.map((failure) => ({
+                ...failure,
+                records: failure.records.map((record) => ({ ...record })),
+            })),
         })),
     };
 }

package/dist/proxy/proxyTraceContext.d.ts

@@ -0,0 +1,21 @@
+import type { ProxyLogTraceContext } from "../types/index.js";
+/** Correlation belongs to the in-flight HTTP request, not to an async callback. */
+export declare function registerProxyRequestTraceContext(requestId: string, ids: ProxyLogTraceContext): void;
+/** Release once transport and terminal accounting have settled. */
+export declare function releaseProxyRequestTraceContext(requestId: string): void;
+/** Internal fallback records share their parent request's trace. */
+export declare function getProxyRequestTraceContext(requestId: string): ProxyLogTraceContext | undefined;
+/** Retain IDs and sampling flags before deferred processing leaves the request. */
+export declare function resolveProxyLogTraceContext(record: {
+    traceId?: unknown;
+    spanId?: unknown;
+    traceFlags?: unknown;
+    requestId?: unknown;
+}): ProxyLogTraceContext | undefined;
+/** Populate native OTLP correlation, including valid unsampled contexts. */
+export declare function proxyLogContext(record: {
+    traceId?: unknown;
+    spanId?: unknown;
+    traceFlags?: unknown;
+    requestId?: unknown;
+}): import("@opentelemetry/api").Context;

package/dist/proxy/proxyTraceContext.js

@@ -0,0 +1,47 @@
+import { context, ROOT_CONTEXT, trace, isSpanContextValid, } from "@opentelemetry/api";
+const requests = new Map();
+/** Correlation belongs to the in-flight HTTP request, not to an async callback. */
+export function registerProxyRequestTraceContext(requestId, ids) {
+    requests.set(requestId, ids);
+}
+/** Release once transport and terminal accounting have settled. */
+export function releaseProxyRequestTraceContext(requestId) {
+    requests.delete(requestId);
+}
+/** Internal fallback records share their parent request's trace. */
+export function getProxyRequestTraceContext(requestId) {
+    return (requests.get(requestId) ??
+        requests.get(requestId.replace(/:codex-fallback$/, "")));
+}
+/** Retain IDs and sampling flags before deferred processing leaves the request. */
+export function resolveProxyLogTraceContext(record) {
+    const saved = typeof record.requestId === "string"
+        ? getProxyRequestTraceContext(record.requestId)
+        : undefined;
+    const active = trace.getSpanContext(context.active());
+    const ids = typeof record.traceId === "string" && typeof record.spanId === "string"
+        ? { traceId: record.traceId, spanId: record.spanId }
+        : (saved ?? active);
+    if (!ids) {
+        return undefined;
+    }
+    const traceFlags = typeof record.traceFlags === "number" &&
+        Number.isInteger(record.traceFlags) &&
+        record.traceFlags >= 0 &&
+        record.traceFlags <= 255
+        ? record.traceFlags
+        : saved?.traceId === ids.traceId
+            ? saved.traceFlags
+            : active?.traceId === ids.traceId
+                ? active.traceFlags
+                : 0;
+    const result = { ...ids, traceFlags };
+    return isSpanContextValid(result)
+        ? { traceId: result.traceId, spanId: result.spanId, traceFlags }
+        : undefined;
+}
+/** Populate native OTLP correlation, including valid unsampled contexts. */
+export function proxyLogContext(record) {
+    const ids = resolveProxyLogTraceContext(record);
+    return ids ? trace.setSpanContext(ROOT_CONTEXT, ids) : context.active();
+}

package/dist/proxy/proxyTracer.d.ts

@@ -14,7 +14,7 @@
  * - TelemetryService for metrics recording
  */
 import { type Span } from "@opentelemetry/api";
-import type { AccountSelectionContext, ProxyRequestContext, ResponseInfoContext, UpstreamAttemptContext, UsageContext } from "../types/index.js";
+import type { AccountSelectionContext, ProxyRequestContext, ResponseInfoContext, UpstreamAttemptContext, UsageContext, RuntimeRequestMetadata, ProxyLogTraceContext } from "../types/index.js";
 declare class ProxyTracer {
     private readonly rootSpan;
     private readonly proxyTracer;
@@ -34,6 +34,8 @@ declare class ProxyTracer {
     private billingProvider;
     private readonly startTime;
     private readonly isStream;
+    private ended;
+    private recordRequestMetrics;
     private accountEmail?;
     private usage?;
     private mode;
@@ -102,10 +104,7 @@ declare class ProxyTracer {
     /** Record request and/or response body sizes for bandwidth tracking. */
     recordBodySizes(requestBytes?: number, responseBytes?: number): void;
     /** Return the OTel trace/span IDs for this request (for log correlation). */
-    getTraceContext(): {
-        traceId: string;
-        spanId: string;
-    };
+    getTraceContext(): ProxyLogTraceContext;
     /** Return the captured usage (set by setUsage). */
     getUsage(): UsageContext | undefined;
     /** End the root span with final HTTP status and duration, and emit OTEL metrics. */
@@ -126,3 +125,8 @@ export declare function recordFallbackAttempt(attrs: {
     durationMs: number;
 }): void;
 export { ProxyTracer };
+/** Standard SERVER span covers every proxy door, including parsing and admission failures. */
+export declare function startProxyHttpTrace(metadata: RuntimeRequestMetadata, headers: Record<string, string>): {
+    run: <T>(fn: () => T) => T;
+    end: (status: number, outcome: string, errorType?: string) => void;
+};