Updated on 2023-12-20 GMT+08:00

Circuit Breaker

Circuit breaker policies protect your backend services when a performance issue occurs. If the backend service of an API times out for N consecutive times or if the latency is long, the downgrade mechanism of a circuit breaker policy is triggered to return an error to the API caller or forward requests to a specified backend. After the backend service recovers, the circuit breaker closes and requests become normal.

If your gateway does not support this policy, contact technical support to upgrade the gateway to the latest version.

Parameter Description

Table 1 Parameter description

Parameter

Description

Policy Type

  • API-specific

    Control requests for a single API.

  • API-sharing

    Control requests for all APIs bound with the policy.

Circuit Breaker Type

Triggering type of the circuit breaker.

  • Timeout downgrade: The circuit breaker will be triggered upon backend timeout.
  • Condition downgrade: The circuit breaker will be triggered when configured match conditions are met.

Condition Type

Triggering mode of the circuit breaker.

  • Count: Once the number of requests that meet conditions within a specified time window reaches the threshold, the circuit breaker is immediately triggered.
  • Percentage: Once the percentage of requests that meet conditions within a specified time window reaches the threshold, the circuit breaker is triggered after the time window expires.

Match Condition

This parameter is required only when Circuit Breaker Type is set to Condition downgrade.

Configure triggering conditions for the circuit breaker.

  • Response Error Codes: The circuit breaker will be triggered if the backend responds with specified status codes.
  • Response Latency: The circuit breaker will be triggered if the backend response latency reached a specified threshold.

Time Window (s)

The period for determining how many times have the conditions been met. Use this parameter together with Threshold or Min Percentage. If the threshold or percentage is reached, the circuit breaker is triggered.

Threshold

This parameter is required only when Condition Type is set to Count.

Set the threshold for triggering the circuit breaker. Use this parameter together with Time Window. Once the number of backend requests that meet the conditions within the time window reaches the threshold, the circuit breaker is triggered.

NOTE:

A circuit breaker policy is triggered for a single gateway component. If your gateway has multiple components, the triggering for each component is determined separately.

If the threshold is reached within the time window for a gateway component, requests sent to the component trigger the circuit breaker, and other gateway components still forward requests normally.

A gateway component is a connection address of your gateway. To view the number of gateway components, go to the Gateway Information page of the gateway and view the number of IP addresses in Private Network Access IP.

Min Calls

This parameter is required only when Condition Type is set to Percentage.

Set the minimum number of API calls that will trigger the circuit breaker within the time period. The circuit breaker will not be triggered if the number of API calls within the time period is less than this value.

Min Percentage (%)

This parameter is required only when Condition Type is set to Percentage.

Set the threshold for triggering the circuit breaker. Use this parameter together with Time Window. Once the percentage of backend requests that meet the conditions within the time window reaches the threshold, the circuit breaker is triggered.

Control Duration (s)

Time for which the circuit breaker will be on. When the time is reached, the circuit breaker will be off.

Backend Downgrade

Determine whether to enable backend downgrade.

  • Enable: Requests for APIs that have triggered a downgrade will be forwarded to a specified backend.
  • Disable: Requests for APIs that have triggered a downgrade will not be forwarded to any backend. Instead, an error message indicating that the service is unavailable will be returned.

Backend Type

This parameter is required only when Backend Downgrade is enabled.

Specify the backend type to which requests will be forwarded when the circuit breaker is on.

  • Mock: The defined response will be returned.
    • Status Code: the status code to be included in the response
    • Response: the response body, which is in JSON format
    • Response Header: header parameters to be included in the response
  • HTTP&HTTPS: Backend requests will be forwarded to a specified HTTP&HTTPS backend service.
    • Load Balance Channel: Determine whether to use a load balance channel to access the backend service. If yes, create a load balance channel in advance.
    • Backend URL: address of the backend service to forward requests to.
    • Timeout (ms): backend request timeout. The default value is 5000 ms.
  • Passthrough: Backend requests will be forwarded to the original API backend.

    To add header parameters to backend requests, click Add Parameter.

Downgrade Parameter Settings

Determine whether to enable downgrade parameter configuration. After this option is enabled, custom rules take precedence over the default triggering conditions and downgrade settings configured above.

  • If a custom rule is matched, the triggering conditions and downgrade settings defined in the rule are applied. If the matched custom rule contains no triggering condition or downgrade settings, the default settings in Trigger Configuration and Backend Downgrade will be applied.
  • If no custom rule is matched, the default settings will be applied.

Parameters

Define parameters for rule matching.

  • Parameter Location: position of a parameter in API requests.
  • Parameter Name: name of a parameter used for rule matching.

By default, the system provides the reqPath (request path) and method (request method) parameters. Click Add Parameter to add parameters.

Rules

Customize matching rules for the circuit breaker. Click Add Rule to add rules. The system matches rules from top to bottom. Adjust the rule priority by moving the rules up or down.

  • Conditions: Click to set condition expressions. If there are three or more expressions, you can layer them by clicking Set Lower Level.
    • =: equal to
    • !=: not equal to
    • pattern: regular expression
    • enum: enumerated values. Separate them with commas (,).
  • For details about how to configure the triggering conditions and backend downgrade, see the instructions for the default settings above.

Example: You have enabled Downgrade Parameter Settings and added rules rule01 and rule02 in sequence. And you have disabled Trigger Configuration and enabled Backend Downgrade for rule01, and have enabled both options for rule02. With these settings, the circuit breaker first checks whether the conditions of rule01 are met. If yes, the circuit breaker is turned on based on the default settings because no triggering condition has been defined in rule01, and backend downgrade configured in rule01 is executed. If no, the check is continued for rule02.

Example Script

{
  "breaker_condition":{
    "breaker_type":"timeout",
    "breaker_mode":"counter",
    "unhealthy_threshold":30,
    "time_window":15,
    "open_breaker_time":15,
    "unhealthy_percentage":51,
    "min_call_threshold":20
  },
  "scope":"share",
  "downgrade_default":{
    "type":"http",
    "passthrough_infos":null,
    "func_info":null,
    "mock_info":null,
    "http_info":{
      "isVpc":false,
      "vpc_channel_id":"",
      "address":"10.10.10.10",
      "scheme":"HTTP",
      "method":"GET",
      "path":"/demo",
      "timeout":5000
    },
    "http_vpc_info":null
  },
  "downgrade_parameters":[
  {
    "name":"reqPath",
    "type":"path",
    "value":"path",
    "disabled":true,
    "focused":true,
    "id":"92002eqbpilg6g"
  },
  {
    "name":"method",
    "type":"method",
    "value":"method",
    "disabled":true,
    "focused":true,
    "id":"tuvxetsdqvcos8"
  }],
  "downgrade_rules":[
  {
    "rule_name":"rule-test1",
    "parameters":[
      "reqPath",
      "method"
    ],
    "match_regex":"[\"reqPath\",\"==\",\"/test\"]",
    "downgrade_backend":{
      "type":"mock",
      "passthrough_infos":null,
      "func_info":null,
      "mock_info":{
        "status_code":200,
        "result_content":"{status: ok}",
        "headers":[]
      },
      "http_info":null,
      "http_vpc_info":null
    },
    "breaker_condition":{
      "breaker_type":"timeout",
      "breaker_mode":"percentage",
      "unhealthy_threshold":30,
      "time_window":15,
      "open_breaker_time":15,
      "unhealthy_percentage":51,
      "min_call_threshold":20
    }
  }]
}