Circuit Breaker

Overview

The Circuit Breaker module protects your upstream services by rejecting traffic to your endpoints when the upstreams become overloaded, allowing them time to recover to a steady operational state.

When your upstream service's 5XX responses exceed a percentage threshold of the total, the circuit breaker 'opens' or 'breaks' the circuit. When the circuit is open, the ngrok edge rejects requests to your endpoint with a 503 error response and does not forward them through to your upstream server.

When the circuit is open, ngrok will allow a small set of requests through to the upstream service to determine whether it has recovered. If those requests are successful, it will close the circuit permitting traffic to flow to your upstream service once again.

Example Usage

Reject traffic to your upstream service if it more than than 50% of its responses have 5XX status codes.

Agent CLI

Loading…

Agent Config

Loading…

SSH

Loading…

Go

Loading…

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithCircuitBreaker

Javascript

Loading…

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#circuit_breaker
• https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#circuitBreaker

Python

Loading…

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.circuit_breaker
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

Loading…

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/config/struct.HttpTunnelBuilder.html#method.circuit_breaker

Kubernetes Controller

Loading…

Behavior

The Circuit Breaker module is an implementation of Netflix's Hystrix circuit breaker specification.

If the upstream service responds with more than the threshold percentage of requests with 5XX status codes, the circuit breaker preemptively reject all subsequent requests at the ngrok edge with a 503 until the upstream service's error rate drops below the threshold percentage.

Circuit breaker state is tracked on each ngrok edge server individually. There are many ngrok edge servers which means that your upstream service may observe requests even after you would expect the circuit breaker to open. All of ngrok's edge servers will eventually open their circuits to protect an failing upstream service but the behavior you observe may not exactly match the parameters you've set because circuit breaker state is tracked individually on each of ngrok's edge servers.

Reference

Configuration

The Agent and Agent SDKs do not support configuration of some parameters of the Circuit Breaker.

Parameter	Default	Description
Error Threshold		The threshold percentage of upstream requests that must fail before the circuit is opened expressed a decimal value between 0 and 1. ngrok defines any HTTP response with a status code greater than or equal to 500 as an error response that counts toward the circuit breaker threshold.
Tripped Duration	10	The number of seconds to reject requests, once the circuit is opened, before rechecking if the circuit should again be closed.
Rolling Window	10	The window of time we keep metrics for the circuit breaker, the error threshold only considers successes and errors that fall within this window.
Number of Buckets	10	The number of discrete time intervals the rolling window duration is divided into. Along with the rolling window duration, this defines the granularity at which requests expire out of the rolling window. Max 128.
Volume Threshold	20	The minimum number of requests required in a rolling window that will trip the circuit.

Upstream Headers

This module does not add any upstream headers.

Errors

Code	HTTP Status	Error
ERR_NGROK_3202	503	This error is returned if the circuit breaker is open because the upstream service is failing.

Events

When the Circuit Breaker module is enabled, it populates the following fields in http_request_complete.v0 events.

Fields
circuit_breaker.decision

Edges

Circuit Breaker is an HTTPS Edge module which can be applied to Routes.

• Circuit Breaker Edge Module API Resource

Pricing

This module is available on all plans.

Try it out

This short Go program below that demonstrates Circuit Breaker behavior. Create the file example.go with the Go code below and then run the following commands.

Loading…

example.go

Loading…