Documentation Documentation

Circuit Breakers

Overview

Circuit Breaker Example

Tyk has a built-in circuit breaker pattern as a path-based option. Our circuit breaker is threshold-based, so if a sample size x of y% requests fail, the breaker will trip. The Gateway will stop all inbound requests to that service for a pre-defined period of time (a recovery time-period). You configure this time period using the return_to_service_after option in your API definition, or setup via the Dashboard. See Configure with the API Definition or Configure with the Dashboard. This also triggers an event which you can hook into to perform corrective or logging action. When a circuit breaker is tripped, it will return a 503 “Service temporarily unavailable” error.

The circuit breaker works across hosts (i.e. if you have multiple targets for an API, the sample is across all upstream requests).

Circuit breakers are individual on a single host, they do not centralise or pool back-end data. This is for speed purposes. This means that in a load balanced environment where multiple Tyk nodes are used, some traffic can spill through as other nodes reach the sampling rate limit.

Events

When a circuit breaker trips, it will fire a BreakerTriggered event which you can define actions for in the event_handlers section (see Event Data and Event Types for more information):

event_handlers: {
  events: {
    BreakerTriggered: [
      {
        handler_name: "eh_web_hook_handler",
        handler_meta: {
          method: "POST",
          target_path: "http://posttestserver.com/post.php?dir=tyk-breaker",
          template_path: "templates/breaker_webhook.json",
          header_map: {
            "X-Tyk-Test-Header": "Tyk v1.BANANA"
          },
          event_timeout: 10
        }
      }
    ]
   }
 },

The status codes returned to the template are:

// BreakerTripped is sent when a breaker trips
BreakerTripped = 0

// BreakerReset is sent when a breaker resets
BreakerReset = 1

NOTE: If you are using the service discovery module, every time the breaker trips, Tyk will attempt to refresh the node list.

Configure with the API Definition

To enable the breaker in your API Definition, you will need to add a new section to your versions’ extended_paths list:

"circuit_breakers": [
  {
    "path": "get",
    "method": "GET",
    "threshold_percent": 0.5,
    "samples": 5,
    "return_to_service_after": 60
  }
]
  • path: The path to match on.
  • method: The method to match on.
  • threshold_percent: The percentage of requests that can error before the breaker is tripped. This must be a value between 0.0 and 1.0.
  • samples: The number of samples to take for a circuit breaker window.
  • return_to_service_after: The cool-down period of the breaker to return to service (seconds).

Configure with the Dashboard

To set up a circuit breaker on a path for your API, add a new Endpoint in the Endpoint Designer section of your API and then select the Circuit Breaker plugin:

Plugin dropdown list

Once the plugin is active, you can set up the various configurations options for the breaker in the drawer by clicking on it:

Circuit breaker configuration form

  • Trigger threshold percentage: The percentage of requests that can error before the breaker is tripped, this must be a value between 0.0 and 1.0.
  • Sample size (requests): The number of samples to take for a circuit breaker window.
  • Return to service in (s): The cool-down period of the breaker to return to service (seconds).