@juspay/neurolink
Version:
Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applicatio
112 lines (111 loc) • 4.91 kB
TypeScript
/**
* Proxy Request Tracer
*
* Creates and manages OTel spans for the proxy request lifecycle.
* Provides a clean API for claudeProxyRoutes to trace each phase:
* receive -> account_selection -> upstream (per retry) -> stream -> end
*
* Uses the existing instrumentation infrastructure:
* - getTracer() from instrumentation.ts for span creation
* - setLangfuseContext() for Langfuse enrichment
* - OtelBridge for context propagation to/from upstream
* - SpanAttributes from spanTypes.ts for attribute naming
* - calculateCost() from pricing.ts for cost tracking
* - TelemetryService for metrics recording
*/
import { type Span } from "@opentelemetry/api";
import type { AccountSelectionContext, ProxyRequestContext, UpstreamAttemptContext, UsageContext } from "../types/index.js";
declare class ProxyTracer {
private readonly rootSpan;
private readonly proxyTracer;
private readonly bridge;
private readonly requestId;
private readonly model;
private readonly startTime;
private readonly isStream;
private accountEmail?;
private usage?;
private mode;
private constructor();
/**
* Create a root span for a proxy request and set Langfuse context.
*
* If the incoming request carries a `traceparent` header, the root span
* will be linked to the caller's trace via OtelBridge.extractContext().
*/
static startRequest(ctx: ProxyRequestContext, incomingHeaders?: Record<string, string>): ProxyTracer;
/** Span covering the initial request receive and parse phase. */
startReceive(): Span;
/** Span covering account selection logic (fill-first / round-robin). */
startAccountSelection(): Span;
/** Span covering a single upstream attempt. One per retry. */
startUpstreamAttempt(ctx: UpstreamAttemptContext): Span;
/** Span covering the SSE stream relay phase. */
startStream(): Span;
/** Record account selection outcome on the root span. */
setAccountSelection(ctx: AccountSelectionContext): void;
/** Record token usage and cost on the root span. */
setUsage(ctx: UsageContext): void;
/** Record an error on the root span. */
setError(errorType: string, errorMessage: string): void;
/** Record whether the request was handled in full or passthrough mode. */
setMode(mode: "full" | "passthrough" | "passthrough-cli"): void;
/**
* Record that the proxy substituted a different model than was requested.
* Sets span attributes and increments the substitution metric counter.
*/
setModelSubstitution(requestedModel: string, actualModel: string): void;
setFallbackInfo(info: {
triggered: boolean;
provider?: string;
model?: string;
attemptCount: number;
reason: string;
}): void;
/** Log the incoming client request body (redacted). */
logRequestBody(body: string): void;
/** Log the incoming client request headers (redacted). */
logRequestHeaders(headers: Record<string, string>): void;
/** Log the upstream request body (redacted, as sent to Anthropic). */
logUpstreamRequestBody(body: string): void;
/** Log the upstream request headers (redacted). */
logUpstreamRequestHeaders(headers: Record<string, string>): void;
/** Log the upstream response headers (redacted). */
logUpstreamResponseHeaders(headers: Record<string, string>): void;
/** Log the upstream response body (redacted). */
logUpstreamResponseBody(body: string): void;
/** Log SSE stream events (each event has type, timestamp, data). */
logStreamEvents(events: Array<{
type: string;
timestamp: number;
data: string;
}>): void;
/** Record an upstream retry attempt. */
recordRetry(account: string, reason: string): void;
/** 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;
};
/** Return the captured usage (set by setUsage). */
getUsage(): UsageContext | undefined;
/** End the root span with final HTTP status and duration, and emit OTEL metrics. */
end(responseStatus: number, durationMs: number): void;
/** Record metrics via TelemetryService (call after setUsage). */
recordMetrics(): void;
/**
* Get trace context headers for propagation to the upstream Anthropic request.
* Injects the current trace's `traceparent` / `tracestate` into a new header map.
*/
getTraceHeaders(): Record<string, string>;
}
export declare function recordFallbackAttempt(attrs: {
provider: string;
model: string;
status: "success" | "failure";
errorMessage?: string;
durationMs: number;
}): void;
export { ProxyTracer };