UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

332 lines (305 loc) • 15.2 kB
import type { ResponsesTerminalStatus } from "../bridge"; import type { KiroQuotaMetricRow } from "../providers/kiro-quota-metrics"; import type { AttemptRecoveryKind } from "../usage/log"; import { REQUEST_FAILURE_CAUSES, type RequestFailureCause, causeForRecoveryKind, } from "../lib/request-failure-model"; import { REQUEST_OUTCOME_CLASSES, classifyRequestOutcome, type RequestOutcomeClass, } from "../usage/request-outcome"; export const REQUEST_METRICS_PROTOCOLS = Object.freeze(["responses", "chat", "messages", "unknown"] as const); /** * The exporter's result label set IS the shared outcome vocabulary, not a copy of it. Restating * these four strings here is what let the exporter and the dashboard drift into disagreeing about * the same request. */ export const REQUEST_METRICS_RESULTS = REQUEST_OUTCOME_CLASSES; /** * Closed recovery classes exported as Prometheus label values. * * Bounded by construction: the label can only ever take one of these strings, so no user, model, * account or request identifier can reach a series name. `quota`, `policy` and `ciphertext` are * separate members because an operator seeing a spike needs to know which one it is -- waiting * out a rate limit, changing accounts, changing the prompt and dropping stale ciphertext are * four different responses, and collapsing them is what made the existing counter unactionable. */ export const REQUEST_METRICS_RECOVERY_CLASSES = Object.freeze([ "transient", "connection", "credential", "rate_limit", "quota", "policy", "ciphertext", "payload", "empty_completion", "effort_downgrade", "fast_downgrade", "other", ] as const); export const REQUEST_DURATION_BUCKETS_SECONDS = Object.freeze([0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60] as const); export const REQUEST_TTFT_BUCKETS_SECONDS = Object.freeze([0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30] as const); /** * The failure-cause label set IS the shared dictionary, for the same reason the result label set * is the shared outcome vocabulary: a restated copy is what let two surfaces drift into * disagreeing about the same request. * * It labels a COUNTER and never a histogram. Fifteen causes across four protocols is sixty * series, fixed for the lifetime of the roster, and every value comes from a frozen list, so no * user, model, account or request identifier can reach a series name. A histogram labelled by * cause would multiply that by its bucket count for no question anyone asks. */ export const REQUEST_METRICS_FAILURE_CAUSES = REQUEST_FAILURE_CAUSES; export type RequestMetricsProtocol = typeof REQUEST_METRICS_PROTOCOLS[number]; export type RequestMetricsResult = RequestOutcomeClass; export type RequestMetricsRecoveryClass = typeof REQUEST_METRICS_RECOVERY_CLASSES[number]; export interface RequestMetricFinalFact { protocol?: "responses" | "chat" | "messages"; status: number; durationMs: number; firstOutputMs?: number; terminalStatus?: ResponsesTerminalStatus; closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow"; attempts?: ReadonlyArray<{ sendCount: number; recoveryKinds: readonly AttemptRecoveryKind[]; }>; spendSends?: number; /** * Why this request failed, as the recorder derived it. Absent when it did not fail, which is * why the counter below cannot be reconstructed by subtracting completions from totals. */ failureCause?: RequestFailureCause; } export interface RequestMetricsRecorder { recordFinalRequest(fact: RequestMetricFinalFact): void; } export interface RequestMetricsSnapshotter { snapshot(): string; } export interface RequestMetricsOwner extends RequestMetricsRecorder, RequestMetricsSnapshotter { resetForTests(): void; } interface HistogramCell { buckets: number[]; count: number; sum: number; } const protocolCell = (value: RequestMetricsProtocol): number => REQUEST_METRICS_PROTOCOLS.indexOf(value); const resultCell = (value: RequestMetricsResult): number => REQUEST_METRICS_RESULTS.indexOf(value); const recoveryCell = (value: RequestMetricsRecoveryClass): number => REQUEST_METRICS_RECOVERY_CLASSES.indexOf(value); const failureCauseCell = (value: RequestFailureCause): number => REQUEST_METRICS_FAILURE_CAUSES.indexOf(value); function matrix(rows: number, columns: number): number[][] { return Array.from({ length: rows }, () => Array.from({ length: columns }, () => 0)); } function histograms(bounds: readonly number[]): HistogramCell[][] { return Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => ( Array.from({ length: REQUEST_METRICS_RESULTS.length }, () => ({ buckets: Array.from({ length: bounds.length + 1 }, () => 0), count: 0, sum: 0, })) )); } /** * Metrics class for each shared failure cause. * * Keyed on the cause rather than on the recovery kind so this projection and the durable log * speak one vocabulary. Total by construction: the previous switch ended in `default: "other"`, * which meant a recovery kind added later compiled cleanly and then disappeared into an * unactionable bucket. A missing member is now a typecheck failure. */ const CAUSE_METRICS_CLASS = { "transport-unsent": "connection", "transport-ambiguous": "connection", "upstream-declined": "transient", "rate-limit": "rate_limit", "quota-exhausted": "quota", "credential-rejected": "credential", "policy-refusal": "policy", "parameter-rejected": "effort_downgrade", "ciphertext-refusal": "ciphertext", "payload-too-large": "payload", "payload-rejected": "payload", "upstream-fault": "transient", "empty-output": "empty_completion", "client-cancelled": "other", "local-refusal": "other", } as const satisfies Record<RequestFailureCause, RequestMetricsRecoveryClass>; function recoveryClass(kind: AttemptRecoveryKind): RequestMetricsRecoveryClass { // Both recoveries answer a rejected parameter, but an operator acts on them differently: // an effort downgrade is a model/effort mismatch, a fast downgrade is a missing Anthropic // fast-mode entitlement. Keep `effort_downgrade` meaning exactly what it always meant. if (kind === "anthropic-fast-downgrade") return "fast_downgrade"; return CAUSE_METRICS_CLASS[causeForRecoveryKind(kind)]; } function observeHistogram(cell: HistogramCell, bounds: readonly number[], value: number): void { if (!Number.isFinite(value) || value < 0) return; cell.count += 1; cell.sum += value; for (let index = 0; index < bounds.length; index += 1) { if (value <= bounds[index]!) cell.buckets[index]! += 1; } cell.buckets[bounds.length]! += 1; } function sampleLabels(protocol: RequestMetricsProtocol, result?: RequestMetricsResult): string { return result === undefined ? `{protocol="${protocol}"}` : `{protocol="${protocol}",result="${result}"}`; } function appendHistogram( lines: string[], name: string, help: string, values: HistogramCell[][], bounds: readonly number[], ): void { lines.push(`# HELP ${name} ${help}`, `# TYPE ${name} histogram`); for (const protocol of REQUEST_METRICS_PROTOCOLS) { for (const result of REQUEST_METRICS_RESULTS) { const cell = values[protocolCell(protocol)]![resultCell(result)]!; for (let index = 0; index < bounds.length; index += 1) { lines.push(`${name}_bucket{protocol="${protocol}",result="${result}",le="${bounds[index]}"} ${cell.buckets[index]}`); } lines.push(`${name}_bucket{protocol="${protocol}",result="${result}",le="+Inf"} ${cell.buckets[bounds.length]}`); lines.push(`${name}_sum${sampleLabels(protocol, result)} ${cell.sum}`); lines.push(`${name}_count${sampleLabels(protocol, result)} ${cell.count}`); } } } function appendKiroQuotaGauges(lines: string[], rows: readonly KiroQuotaMetricRow[]): void { const families = [ ["opencodex_kiro_quota_used_credits", "Cached Kiro plan credits used.", "used"], ["opencodex_kiro_quota_limit_credits", "Cached Kiro plan credit limit.", "limit"], ["opencodex_kiro_quota_used_percent", "Cached Kiro plan percent used.", "percent"], ["opencodex_kiro_quota_seconds_to_reset", "Seconds until the observed Kiro reset.", "secondsToReset"], ] as const; const labels = new Set<string>(); const valid = rows.slice(0, 32).filter(row => { if (!/^o[0-9a-f]{6}$/.test(row.account) || labels.has(row.account)) return false; if (![row.used, row.limit, row.percent].every(value => Number.isFinite(value) && value >= 0)) return false; if (row.limit <= 0 || row.percent > 100) return false; labels.add(row.account); return true; }); for (const [name, help, key] of families) { lines.push(`# HELP ${name} ${help}`, `# TYPE ${name} gauge`); for (const row of valid) { const value = row[key]; if (typeof value === "number" && Number.isFinite(value) && value >= 0) lines.push(`${name}{account="${row.account}"} ${value}`); } } } export function createRequestMetricsOwner( processStartTimeSeconds = Date.now() / 1000, kiroQuotaRows?: () => readonly KiroQuotaMetricRow[], ): RequestMetricsOwner { let logicalRequests = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length); let physicalSends = Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => 0); let recoveries = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RECOVERY_CLASSES.length); let failureCauses = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_FAILURE_CAUSES.length); let durations = histograms(REQUEST_DURATION_BUCKETS_SECONDS); let ttft = histograms(REQUEST_TTFT_BUCKETS_SECONDS); let missingTtft = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length); return { recordFinalRequest(fact): void { const protocol: RequestMetricsProtocol = fact.protocol ?? "unknown"; const result = classifyRequestOutcome(fact); const protocolIndex = protocolCell(protocol); const resultIndex = resultCell(result); logicalRequests[protocolIndex]![resultIndex]! += 1; const attempts = fact.attempts; const sends = attempts === undefined ? (Number.isInteger(fact.spendSends) && fact.spendSends! >= 0 ? fact.spendSends! : 0) : attempts.reduce((total, attempt) => ( Number.isInteger(attempt.sendCount) && attempt.sendCount >= 0 ? total + attempt.sendCount : total ), 0); physicalSends[protocolIndex]! += sends; // Counted from the cause the recorder derived, not re-derived here. Two derivations of one // answer is the disagreement this batch exists to remove, and the recorder is the only // place that sees the transport facts a cause needs. if (fact.failureCause !== undefined) { failureCauses[protocolIndex]![failureCauseCell(fact.failureCause)]! += 1; } for (const attempt of attempts ?? []) { for (const kind of new Set(attempt.recoveryKinds)) { recoveries[protocolIndex]![recoveryCell(recoveryClass(kind))]! += 1; } } observeHistogram(durations[protocolIndex]![resultIndex]!, REQUEST_DURATION_BUCKETS_SECONDS, fact.durationMs / 1000); if (typeof fact.firstOutputMs === "number" && Number.isFinite(fact.firstOutputMs) && fact.firstOutputMs >= 0) { observeHistogram(ttft[protocolIndex]![resultIndex]!, REQUEST_TTFT_BUCKETS_SECONDS, fact.firstOutputMs / 1000); } else { missingTtft[protocolIndex]![resultIndex]! += 1; } }, snapshot(): string { const lines: string[] = [ "# HELP opencodex_logical_requests_total Finalized logical requests in this process.", "# TYPE opencodex_logical_requests_total counter", ]; for (const protocol of REQUEST_METRICS_PROTOCOLS) { for (const result of REQUEST_METRICS_RESULTS) { lines.push(`opencodex_logical_requests_total${sampleLabels(protocol, result)} ${logicalRequests[protocolCell(protocol)]![resultCell(result)]}`); } } lines.push( "# HELP opencodex_physical_sends_total Upstream sends made by finalized logical requests in this process.", "# TYPE opencodex_physical_sends_total counter", ); for (const protocol of REQUEST_METRICS_PROTOCOLS) { lines.push(`opencodex_physical_sends_total${sampleLabels(protocol)} ${physicalSends[protocolCell(protocol)]}`); } lines.push( "# HELP opencodex_recoveries_total Distinct recovery kinds observed per physical attempt in this process.", "# TYPE opencodex_recoveries_total counter", ); for (const protocol of REQUEST_METRICS_PROTOCOLS) { for (const recovery of REQUEST_METRICS_RECOVERY_CLASSES) { lines.push(`opencodex_recoveries_total{protocol="${protocol}",recovery="${recovery}"} ${recoveries[protocolCell(protocol)]![recoveryCell(recovery)]}`); } } lines.push( "# HELP opencodex_request_failures_total Finalized logical requests that did not deliver an answer, by derived cause.", "# TYPE opencodex_request_failures_total counter", ); for (const protocol of REQUEST_METRICS_PROTOCOLS) { for (const cause of REQUEST_METRICS_FAILURE_CAUSES) { lines.push(`opencodex_request_failures_total{protocol="${protocol}",cause="${cause}"} ${failureCauses[protocolCell(protocol)]![failureCauseCell(cause)]}`); } } appendHistogram(lines, "opencodex_request_duration_seconds", "Finalized logical request duration in seconds.", durations, REQUEST_DURATION_BUCKETS_SECONDS); appendHistogram(lines, "opencodex_ttft_seconds", "Observed time to first output in seconds.", ttft, REQUEST_TTFT_BUCKETS_SECONDS); lines.push( "# HELP opencodex_ttft_missing_total Finalized logical requests without an observed time to first output.", "# TYPE opencodex_ttft_missing_total counter", ); for (const protocol of REQUEST_METRICS_PROTOCOLS) { for (const result of REQUEST_METRICS_RESULTS) { lines.push(`opencodex_ttft_missing_total${sampleLabels(protocol, result)} ${missingTtft[protocolCell(protocol)]![resultCell(result)]}`); } } appendKiroQuotaGauges(lines, kiroQuotaRows?.() ?? []); lines.push( "# HELP opencodex_metrics_process_start_time_seconds Unix time when this process metrics owner started.", "# TYPE opencodex_metrics_process_start_time_seconds gauge", `opencodex_metrics_process_start_time_seconds ${processStartTimeSeconds}`, ); return `${lines.join("\n")}\n`; }, resetForTests(): void { logicalRequests = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length); physicalSends = Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => 0); recoveries = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RECOVERY_CLASSES.length); failureCauses = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_FAILURE_CAUSES.length); durations = histograms(REQUEST_DURATION_BUCKETS_SECONDS); ttft = histograms(REQUEST_TTFT_BUCKETS_SECONDS); missingTtft = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length); }, }; }