/**
 * 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 };