Skip to main content

Circuit Breaker

Overview​

The Circuit Breaker action helps maintain system reliability by rejecting requests when the error rate and request volume within a rolling window exceed defined thresholds. It pauses traffic temporarily to allow the system to recover and automatically re-evaluates upstream health before resuming.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request

Type​

circuit-breaker

Configuration Fields​

  • error_thresholdfloatRequired

    Threshold percentage of errors that must be met before requests are rejected. Must be a value between 0.0 and 1.0. Defaults to 0.5.

  • volume_thresholdinteger

    Number of requests in a rolling window before checking the error threshold. Must be a number between 1 and 2,000,000,000. Defaults to 10.

  • window_durationduration

    Number of seconds in the rolling window that metrics are retained for. Must be a value between 1s and 2m. Defaults to 10s.

  • tripped_durationduration

    Number of seconds the system waits after rejecting a request before re-evaluating upstream health. Must be a value between 1s and 2m. Defaults to 10s.

  • num_bucketsinteger

    Number of buckets that metrics are divided into within the rolling window. Fixed at 10.

  • enforceboolean

    Determines if the circuit breaker is active. If false, the circuit breaker never trips, and no requests are rejected. Defaults to true.

Examples​

Basic Example​

This example configuration sets up an endpoint (hotdog.ngrok.io) that allows only 1 request every 60 seconds and trips the circuit breaker for 2 minutes.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: circuit-breaker
        config:
          error_threshold: 0
          volume_threshold: 1
          window_duration: 60s
          tripped_duration: 2m
          enforce: true

Start Endpoint with Traffic Policy​

ngrok http 8080 --url hotdog.ngrok.io --traffic-policy-file /path/to/policy.yml

Helper script​

import requests
import time

# Replace with your domain
url = "https://hotdog.ngrok.io"

attempt = 1

while True:
    try:
        response = requests.get(url)

        # Log the response
        if response.status_code == 200:
            print(f"Attempt {attempt}: Success ({response.status_code})")
        else:
            print(f"Attempt {attempt}: Failure ({response.status_code})")

        # Stop when circuit breaker trips
        if response.status_code == 503:
            print("\nCircuit breaker tripped!")
            break
    except requests.exceptions.RequestException as e:
        print(f"Attempt {attempt}: Error ({e})")
        break

    attempt += 1
    time.sleep(0.01)  # Reduce delay for faster request rate
➜  ~ python3  circuit_breaker.py
Attempt 1: Success (200)
Attempt 2: Failure (503)

Circuit breaker tripped!