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

This is the Traffic Policy configuration reference for this action.

Action Type

circuit-breaker

Configuration Fields

Parameter	Type	Description
error_threshold	float	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_threshold	int	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_duration	duration	Number of seconds in the rolling window that metrics are retained for. Must be a value between 1s and 2m. Defaults to 10s.
tripped_duration	duration	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_buckets	int	Number of buckets that metrics are divided into within the rolling window. Fixed at 10.
enforce	bool	Determines if the circuit breaker is active. If false, the circuit breaker never trips, and no requests are rejected. Defaults to true.

Supported Directions

• on-http-request

Supported Schemes

• https
• http

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 3 minutes.

Example Traffic Policy Document

YAML

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

JSON

{
  "on_http_request": [
    {
      "actions": [
        {
          "type": "circuit-breaker",
          "config": {
            "error_threshold": 0,
            "volume_threshold": 1,
            "window_duration": "60s",
            "tripped_duration": "3m",
            "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!