Plug-ins of the Circuit Breaker type

1. Overview

API Gateway provides a circuit breaker for each API to protect the API in the event of abnormal backend performance. By default, if timeout occurs 1,000 times at the backend of an API within 30 seconds, the circuit breaker trips. The circuit breaker stays open for 90 seconds, during which the following error is returned for all API requests: Status=503,X-Ca-Error-Code=D503CB. After 90 seconds, the circuit breaker allows a limited number of concurrent API requests to pass through. If these requests are successful, the circuit breaker closes and API requests can be handled as expected again.

You can also bind a plug-in of the Circuit Breaker type to an API to customize the configurations of its circuit breaker. Take note that plug-ins of the Circuit Breaker type take effect only for APIs on dedicated instances. You can customize the following configurations of a circuit breaker:

• The condition under which the circuit breaker trips. You can specify that the circuit breaker trips after the number of occurrences of timeout, the number of occurrences of a long response time, or the number of occurrences of a specified error, at the backend reaches a threshold within a specified period of time.

• The time window during which the number of occurrences of timeout, the number of occurrences of a long response time, or the number of occurrences of a specified error, at the backend is checked by the circuit breaker to determine whether to trip.

• The period of time during which the circuit breaker stays open after it trips.

• The backend to which API requests are directed when the circuit breaker is open.

2. Configurations

Plug-ins of the Circuit Breaker type take effect only for APIs on dedicated instances. If you bind a plug-in of the Circuit Breaker type to an API on a shared instance, the circuit breaker still uses the default configurations.

2.1 Specify that the circuit breaker trips after the number of occurrences of timeout at the backend reaches a threshold

When you configure a plug-in of the Circuit Breaker type, you can specify that the circuit breaker trips after the number of occurrences of timeout at the backend reaches a threshold within a specified period of time. If the backend timeout threshold specified for an API is 10 seconds and no response is received from the backend within 10 seconds, one occurrence of timeout is counted.

timeoutThreshold: 15         # The threshold of the number of occurrences of timeout at the backend.
windowInSeconds: 30          # The time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15       # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend:            # The backend to which API requests are directed when the circuit breaker is open.
  type: mock
  statusCode: 418

In the preceding code snippet, you can specify the following parameters:

• timeoutThreshold: the threshold of the number of occurrences of timeout at the backend. If this threshold is reached, the circuit breaker trips. The maximum value of this parameter is 5000. We recommend that you specify an appropriate value. If the value is too small, the circuit breaker trips after timeout occurs only several times.

• windowsInSeconds: the time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip. Valid values: 10 to 90. Unit: seconds.

• openTimeoutSeconds: the period of time during which the circuit breaker stays open after it trips. Valid values: 15 to 300. Unit: seconds.

• downgradeBackend: optional. The backend to which API requests are directed when the circuit breaker is open.

2.2 Specify that the circuit breaker trips after the number of occurrences of a long response time at the backend reaches a threshold

When you configure a plug-in of the Circuit Breaker type, you can specify that the circuit breaker trips after the number of occurrences of a long response time at the backend reaches a threshold within a specified period of time. The backend response time is the duration between when API Gateway sends a request to the backend and when API Gateway receives a response from the backend.

---
errorThreshold: 10          # The threshold of the number of occurrences of a long response time.
windowInSeconds: 60             # The time window during which the number of occurrences of a long response time is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 120          # The period of time during which the circuit breaker stays open after it trips.
errorCondition: "$LatencyMilliSeconds > 500"     # The conditional expression that is used to determine whether the backend response time is counted as a long response time. In this example, if the backend response time exceeds 500 ms, it is considered as a long response time.
downgradeBackend:               # The backend to which API requests are directed when the circuit breaker is open.
  type: mock
  statusCode: 403

In the preceding code snippet, you can specify the following parameters:

• errorThreshold: the threshold of the number of occurrences of a long response time.

• windowsInSeconds: the time window during which the number of occurrences of a long response time is checked by the circuit breaker to determine whether to trip. Valid values: 10 to 90. Unit: seconds.

• openTimeoutSeconds: the period of time during which the circuit breaker stays open after it trips. Valid values: 15 to 300. Unit: seconds.

• errorCondition: the conditional expression that is used to determine whether the backend response time is counted as a long response time. You can use the $LatencyMilliSeconds and $LatencySeconds variables. The unit of $LatencyMilliSeconds is milliseconds. The unit of $LatencySeconds is seconds.

• downgradeBackend: optional. The backend to which API requests are directed when the circuit breaker is open.

2.3 Specify that the circuit breaker trips after the number of occurrences of a specified error at the backend reaches a threshold

When you configure a plug-in of the Circuit Breaker type, you can specify that the circuit breaker trips after the number of occurrences of a specified error at the backend reaches a threshold within a specified period of time.

errorCondition: "$StatusCode == 503"  # The conditional expression that specifies the error whose number of occurrences is checked by the circuit breaker to determine whether to trip.
errorThreshold: 1000                  # The threshold of the number of occurrences of the specified error.
windowInSeconds: 30                   # The time window during which the number of occurrences of the specified error at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15                # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend:                     # The backend to which API requests are directed when the circuit breaker is open.
  type: "HTTP"
  address: "http://api.foo.com"
  path: "/system-busy.json"
  method: GET

• errorCondition: the conditional expression that specifies the error whose number of occurrences is checked by the circuit breaker to determine whether to trip. You can use the $StatusCode and $LatencySeconds variables.

  • If you specify a conditional expression as $StatusCode = 503 or $StatusCode = 504, the circuit breaker checks the total number of occurrences of HTTP status codes 503 and 504.

  • If you specify a conditional expression as $LatancySeconds > 30, the circuit breaker checks the total number of occurrences of timeout that is greater than 30 seconds.

• errorThreshold: the threshold of the number of occurrences of the specified error.

• windowsInSeconds: the time window during which the number of occurrences of the specified error at the backend is checked by the circuit breaker to determine whether to trip. Valid values: 10 to 90. Unit: seconds.

• openTimeoutSeconds: the period of time during which the circuit breaker stays open after it trips. Valid values: 15 to 300. Unit: seconds.

• downgradeBackend: optional. The backend to which API requests are directed when the circuit breaker is open.

3. Specify the backend to which API requests are directed when the circuit breaker is open

You can set the downgradeBackend parameter to specify a backend to which API requests are directed when the circuit breaker is open. The configurations of the backend must be consistent with the API specification files that are imported to API Gateway. For more information, see Import Swagger files to create APIs. You can configure the following types of backends by using the samples:

• HTTP

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  path: "/users/{userId}"
  method: GET
  timeout: 7000        

• HTTP-VPC

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  path: "/users/{userId}"
  method: GET
  timeout: 10000        

• Function Compute

---
backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"        

• MOCK

---
backend:
  type: MOCK
  mockResult: "mock resul sample"
  mockStatusCode: 200
  mockHeaders:
    - name: Content-Type
      value: text-plain
    - name: Content-Language
      value: zhCN

4. Error codes

5. Limits

• Plug-ins of the Circuit Breaker type take effect only for APIs on dedicated instances.

• Each conditional expression can contain a maximum of 512 characters.

• For each plug-in of the Circuit Breaker type, you can configure a maximum of 50 KB of metadata.