[GitHub] [apisix] yzeng25 commented on a diff in pull request #7050: docs: update "Traffic" Plugin docs 2

[GitBox <gi...@apache.org>]

yzeng25 commented on code in PR #7050:
URL: https://github.com/apache/apisix/pull/7050#discussion_r873311667


##########
docs/en/latest/plugins/api-breaker.md:
##########
@@ -23,40 +29,28 @@ title: api-breaker
 
 ## Description
 
-The plugin implements API fuse functionality to help us protect our upstream business services.
+The `api-breaker` Plugin implements circuit breaker functionality to protect Upstream services.
 
-> About the breaker timeout logic
+Whenever the Upstream service responds with a status code from the configured `unhealthy.http_statuses` list for the configured `unhealthy.failures` number of times, the Upstream service will be considered unhealthy.
 
-the code logic automatically **triggers the unhealthy state** incrementation of the number of operations.
+The request is then retried in 2, 4, 8, 16 ... seconds until the `max_breaker_sec`.
 
-Whenever the upstream service returns a status code from the `unhealthy.http_statuses` configuration (e.g., 500), up to `unhealthy.failures` (e.g., three times) and considers the upstream service to be in an unhealthy state.
-
-The first time unhealthy status is triggered, **broken for 2 seconds**.
-
-Then, the request is forwarded to the upstream service again after 2 seconds, and if the `unhealthy.http_statuses` status code is returned, and the count reaches `unhealthy.failures` again, **broken for 4 seconds**.
-
-and so on, 2, 4, 8, 16, 32, 64, ..., 256, 300. `300` is the maximum value of `max_breaker_sec`, allow users to specify.
-
-In an unhealthy state, when a request is forwarded to an upstream service and the status code in the `healthy.http_statuses` configuration is returned (e.g., 200) that `healthy.successes` is reached (e.g., three times), and the upstream service is considered healthy again.
+In an unhealthy state, if the Upstream service responds with a status code from the configured list `healthy.http_statuses` for `healthy.successes` times, the service is considered healthy again.
 
 ## Attributes
 
-| Name                    | Type          | Requirement | Default | Valid            | Description                                                                 |
-| ----------------------- | ------------- | ----------- | -------- | --------------- | --------------------------------------------------------------------------- |
-| break_response_code     | integer        | required |            | [200, ..., 599] | Return error code when unhealthy |
-| break_response_body     | string         | optional |            |                 | Return response body when unhealthy |
-| break_response_headers  | array[object]  | optional |            |                 | New headers for the response. The values in the header can contain Nginx variables like `$remote_addr` and `$balancer_ip`. This field is in effective only if `break_response_body` is configured. |
-| max_breaker_sec         | integer        | optional | 300        | >=3             | Maximum breaker time(seconds) |
-| unhealthy.http_statuses | array[integer] | optional | {500}      | [500, ..., 599] | Status codes when unhealthy |
-| unhealthy.failures      | integer        | optional | 3          | >=1             | Number of consecutive error requests that triggered an unhealthy state |
-| healthy.http_statuses   | array[integer] | optional | {200}      | [200, ..., 499] | Status codes when healthy |
-| healthy.successes       | integer        | optional | 3          | >=1             | Number of consecutive normal requests that trigger health status |
+| Name                    | Type           | Required | Default | Valid values    | Description                                                                               |
+|-------------------------|----------------|----------|---------|-----------------|-------------------------------------------------------------------------------------------|
+| break_response_code     | integer        | True     |         | [200, ..., 599] | HTTP error code to return when Upstream is unhealthy.                                     |
+| max_breaker_sec         | integer        | False    | 300     | >=3             | Maximum time in seconds for circuit breaking.                                             |
+| unhealthy.http_statuses | array[integer] | False    | {500}   | [500, ..., 599] | Status codes of Upstream to be considered unhealthy.                                      |
+| unhealthy.failures      | integer        | False    | 3       | >=1             | Number of consecutive failures for the Upstream service to be considered unhealthy.       |
+| healthy.http_statuses   | array[integer] | False    | {200}   | [200, ..., 499] | Status codes of Upstream to be considered healthy.                                        |
+| healthy.successes       | integer        | False    | 3       | >=1             | Number of consecutive healthy requests for the Upstream service to be considered healthy. |
 
-## How To Enable
+## Enabling the Plugin
 
-Here's an example, enable the `api-breaker` plugin on the specified route.
-
-Response 500 or 503 three times in a row to trigger a unhealthy. Response 200 once in a row to restore healthy.
+The example below shows how you can configure the Plugin on a specific Route:
 
 ```shell

Review Comment:
   Either `bash` or `shell` is fine (though they have different meanings), when it comes to referring them in code block as `bash` and `shell`, they have the same behaviors. 
   
   I think you should consider specifying them in guidelines as well.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org