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

Example Traffic Policy Document​

---
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!

Action Result Variables​

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

This action does not set any variables after it has been executed.