feat: add request retry observability

Author: ndycode

index.ts

@@ -350,22 +350,27 @@ let sessionAffinityWriteVersion = 0;
 
 	type RuntimeMetrics = {
 		startedAt: number;
-		totalRequests: number;
-		successfulRequests: number;
-		failedRequests: number;
-		rateLimitedResponses: number;
-		serverErrors: number;
-		networkErrors: number;
-		userAborts: number;
-		authRefreshFailures: number;
-		emptyResponseRetries: number;
-		accountRotations: number;
-		sameAccountRetries: number;
-		streamFailoverAttempts: number;
-		streamFailoverRecoveries: number;
-		streamFailoverCrossAccountRecoveries: number;
-		cumulativeLatencyMs: number;
-		lastRequestAt: number | null;
+	totalRequests: number;
+	successfulRequests: number;
+	failedRequests: number;
+	outboundRequestAttemptBudget: number | null;
+	outboundRequestAttemptsConsumed: number;
+	requestAttemptBudgetExhaustions: number;
+	rateLimitedResponses: number;
+	serverErrors: number;
+	networkErrors: number;
+	userAborts: number;
+	authRefreshFailures: number;
+	emptyResponseRetries: number;
+	accountRotations: number;
+	sameAccountRetries: number;
+	streamFailoverAttempts: number;
+	streamFailoverCandidatesConsidered: number;
+	lastStreamFailoverCandidateCount: number;
+	streamFailoverRecoveries: number;
+	streamFailoverCrossAccountRecoveries: number;
+	cumulativeLatencyMs: number;
+	lastRequestAt: number | null;
 		lastError: string | null;
 	};
 
@@ -374,6 +379,9 @@ let sessionAffinityWriteVersion = 0;
 		totalRequests: 0,
 		successfulRequests: 0,
 		failedRequests: 0,
+		outboundRequestAttemptBudget: null,
+		outboundRequestAttemptsConsumed: 0,
+		requestAttemptBudgetExhaustions: 0,
 		rateLimitedResponses: 0,
 		serverErrors: 0,
 		networkErrors: 0,
@@ -383,6 +391,8 @@ let sessionAffinityWriteVersion = 0;
 		accountRotations: 0,
 		sameAccountRetries: 0,
 		streamFailoverAttempts: 0,
+		streamFailoverCandidatesConsidered: 0,
+		lastStreamFailoverCandidateCount: 0,
 		streamFailoverRecoveries: 0,
 		streamFailoverCrossAccountRecoveries: 0,
 		cumulativeLatencyMs: 0,
@@ -935,21 +945,39 @@ let sessionAffinityWriteVersion = 0;
 									emptyResponseMaxRetries,
 									streamFailoverMax,
 								});
+							runtimeMetrics.outboundRequestAttemptBudget =
+								maxOutboundRequestAttempts;
+							logDebug("Configured outbound request attempt budget.", {
+								budget: maxOutboundRequestAttempts,
+								accountCount: accountManager.getAccountCount(),
+								maxSameAccountRetries,
+								emptyResponseMaxRetries,
+								streamFailoverMax,
+							});
 							let outboundRequestAttemptsRemaining =
 								maxOutboundRequestAttempts;
 							const tryConsumeOutboundRequestAttempt = (
 								reason: "primary" | "stream-failover",
 								accountIndex: number,
 							): boolean => {
 								if (outboundRequestAttemptsRemaining <= 0) {
+									runtimeMetrics.requestAttemptBudgetExhaustions += 1;
 									runtimeMetrics.lastError =
 										`Request attempt budget exhausted after ${maxOutboundRequestAttempts} outbound request(s)`;
 									logWarn(
-										`Stopping ${reason} replay after exhausting ${maxOutboundRequestAttempts} outbound request(s) on account ${accountIndex + 1}.`,
+										"Request attempt budget exhausted.",
+										{
+											reason,
+											accountIndex,
+											budget: maxOutboundRequestAttempts,
+											consumed:
+												runtimeMetrics.outboundRequestAttemptsConsumed,
+										},
 									);
 									return false;
 								}
 
+								runtimeMetrics.outboundRequestAttemptsConsumed += 1;
 								outboundRequestAttemptsRemaining -= 1;
 								return true;
 							};
@@ -2063,6 +2091,19 @@ let sessionAffinityWriteVersion = 0;
 															(candidate) => candidate.index,
 														),
 													);
+												runtimeMetrics.lastStreamFailoverCandidateCount =
+													streamFallbackCandidateOrder.length;
+												runtimeMetrics.streamFailoverCandidatesConsidered +=
+													streamFallbackCandidateOrder.length;
+												logDebug(
+													"Prepared stream failover candidates.",
+													{
+														primaryAccountIndex: account.index,
+														candidateCount:
+															streamFallbackCandidateOrder.length,
+														candidateIndices: streamFallbackCandidateOrder,
+													},
+												);
 												responseForSuccess = withStreamingFailover(
 													response,
 													async (failoverAttempt, emittedBytes) => {

test/index-retry.test.ts

@@ -486,6 +486,10 @@ describe("OpenAIAuthPlugin rate-limit retry", () => {
 	});
 
 	it("stops after the bounded outbound request budget even when more accounts are available", async () => {
+		const logger = await import("../lib/logger.js");
+		const logDebugSpy = vi.spyOn(logger, "logDebug").mockImplementation(() => {});
+		const logWarnSpy = vi.spyOn(logger, "logWarn").mockImplementation(() => {});
+
 		const accounts = Array.from({ length: 8 }, (_, index) =>
 			createMockAccount({
 				index,
@@ -540,6 +544,25 @@ describe("OpenAIAuthPlugin rate-limit retry", () => {
 					"Request attempt budget exhausted after 6 outbound request(s). Try again after the current retries settle.",
 			},
 		});
+		expect(logDebugSpy).toHaveBeenCalledWith(
+			"Configured outbound request attempt budget.",
+			expect.objectContaining({
+				budget: 6,
+				accountCount: 8,
+				maxSameAccountRetries: 1,
+				emptyResponseMaxRetries: 2,
+				streamFailoverMax: 1,
+			}),
+		);
+		expect(logWarnSpy).toHaveBeenCalledWith(
+			"Request attempt budget exhausted.",
+			expect.objectContaining({
+				reason: "primary",
+				accountIndex: 6,
+				budget: 6,
+				consumed: 6,
+			}),
+		);
 	});
 
 	it("rebuilds request headers after rotating to the next workspace", async () => {