feat(observability): add circuit-breaker state transition metrics

src/lib/monitoring/metrics.ts

@@ -40,6 +40,26 @@ export function recordAuthMetric(
   createCounterMetric(name, 1, tags);
 }
 
+/** Circuit breaker state machine states. */
+export type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+/**
+ * Record a circuit breaker state transition as a counter. The metric is
+ * named `circuit_breaker.state_change` and tagged with the previous and new
+ * states so dashboards can count each transition independently.
+ */
+export function recordCircuitBreakerStateChange(
+  previousState: CircuitBreakerState,
+  newState: CircuitBreakerState,
+  tags?: Record<string, string | number | boolean>,
+): void {
+  createCounterMetric('circuit_breaker.state_change', 1, {
+    from: previousState,
+    to: newState,
+    ...tags,
+  });
+}
+
 /** Rolling window used to turn individual request outcomes into a rate. */
 export const DEFAULT_ERROR_RATE_WINDOW_MS = 60_000;
 

src/utils/circuitBreaker.ts

@@ -10,6 +10,8 @@
  * - HALF_OPEN: Testing if the system has recovered
  */
 
+import { recordCircuitBreakerStateChange } from '@/lib/monitoring/metrics';
+
 export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
 
 export interface CircuitBreakerConfig {
@@ -173,7 +175,8 @@ export class CircuitBreaker {
    * Transition to a new state
    */
   private transitionTo(newState: CircuitState): void {
-    if (this.state === newState) return;
+    const previousState = this.state;
+    if (previousState === newState) return;
 
     this.state = newState;
     this.lastStateChange = Date.now();
@@ -188,6 +191,8 @@ export class CircuitBreaker {
     } else if (newState === 'HALF_OPEN') {
       this.successCount = 0;
     }
+
+    recordCircuitBreakerStateChange(previousState, newState);
   }
 
   /**
@@ -210,13 +215,10 @@ export class CircuitBreaker {
    * Manually reset the circuit breaker
    */
   reset(): void {
-    this.state = 'CLOSED';
-    this.failureCount = 0;
-    this.successCount = 0;
-    this.lastFailureTime = undefined;
-    this.lastStateChange = Date.now();
+    this.transitionTo('CLOSED');
     this.failureHistory = [];
     this.recoveryDeadline = undefined;
+    this.lastFailureTime = undefined;
   }
 
   /**