Plug-ins of the Circuit Breaker type

1. Overview

API Gateway provides a circuit breaker for each API operation to protect the API operation in the event of abnormal backend performance. By default, if timeout occurs 1,000 times at the backend of an API operation within 30 seconds, the circuit breaker trips. The circuit 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 closes and API requests can be properly handled again.

You can also bind a plug-in of the Circuit Breaker type to an API operation to customize the configurations of its circuit breaker. Notice that plug-ins of the Circuit Breaker type take effect only for API operations 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, 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, 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 is open.

2. Configurations

Plug-ins of the Circuit Breaker type take effect only for API operations on dedicated instances. If you bind a plug-in of the Circuit Breaker type to an API operation in 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. Specify the parameters in the following code snippet:

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 is open.
  type: mock
  statusCode: 418

As shown in the 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.
• windowInSeconds: 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 is open.

2.2. 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. Specify the parameters in the following code snippet:

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 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.
• windowInSeconds: 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 is open.

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

You can specify the downgradeBackend parameter to configure a backend to which API requests are directed when the circuit is open. Configurations of the backend must be consistent with the OpenAPI specification files that are imported to API Gateway. For more information, see Create APIs By Importing Swagger. 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 API operations 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 16,380 bytes of metadata.