Circuit Breaker

Updated on 2025-01-24 GMT+08:00

View PDF

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.

NOTE:

If your gateway does not support this policy, submit a service ticket to upgrade the gateway to the latest version.

Constraints

An API can be bound with only one circuit breaker policy for a given environment, but each circuit breaker policy can be bound to multiple APIs.
Policies are independent of APIs. A policy takes effect for an API only after they are bound to each other. When binding a policy to an API, you must specify an environment where the API has been published. The policy takes effect for the API only in the specified environment.
After you bind a policy to an API, unbind the policy from the API, or update the policy, you do not need to publish the API again.
Taking an API offline does not affect the policies bound to it. The policies are still bound to the API if the API is published again.
Policies that have been bound to APIs cannot be deleted.

Creating a Circuit Breaker Policy

Go to the APIG console.
Select a dedicated gateway at the top of the navigation pane.

In the navigation pane, choose API Management > API Policies.
On the Policies tab, click Create Policy.
On the Select Policy Type page, select Circuit Breaker in the Plug-ins area.

Set the policy information based on the following table.

**Table 1** Circuit breaker parameters
Parameter	Description
Name	Enter a policy name. Using naming rules facilitates future search. It can contain 3 to 255 characters and must start with a letter. Only letters, digits, and underscores (_) are allowed.
Type	Fixed as Circuit Breaker.
Description	Description about the plug-in. Enter 1 to 255 characters.
Policy Content	Content of the plug-in, which can be configured in a form or using a script.
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. 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. 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. 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, HTTP status code 503 and 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. For security purposes, do not include sensitive information in these parameters. 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. FunctionGraph: Backend requests will be forwarded to a specified function. Function URN: the unique identifier of a function. Click Select to select a function. Function Name: automatically displayed after you select a function. Version/Alias: version or alias of the function to be used to receive backend requests. Invocation Mode: the mode in which the function is invoked. Synchronous: When receiving an invocation request, FunctionGraph immediately processes the request and returns a result. The client closes the connection once it has received a response from the backend. Asynchronous: After receiving an invocation request, FunctionGraph queues the request and returns the result after the request is successfully processed. The server processes the queuing requests one by one when it is idle. The client does not care about the invocation result. 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. For security purposes, do not include sensitive information in these parameters. 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.

Click OK.

To clone this policy, click Clone in the Operation column. The name of a cloned policy cannot be the same as that of any existing policy.
After the policy is created, perform the operations described in Binding the Policy to APIs to apply the policy for the API.

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
    }
  }]
}

Binding the Policy to APIs

Click the policy name to go to the policy details page.
Select an environment and click Select APIs.
Select the API group, environment, and required APIs.

APIs can be filtered by API name or tag. The tag is defined during API creation.
Click OK.
- If an API no longer needs this policy, click Unbind in the row that contains the API.
- If there are multiple APIs that no longer need this policy, select these APIs, and click Unbind above the API list. You can unbind a policy from a maximum of 1000 APIs at a time.

Parent topic: Configuring API Plug-in Policies

Previous topic: Kafka Log Push

Next topic: Third-Party Authorizer

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot