juzhiyuan commented on code in PR #7050:
URL: https://github.com/apache/apisix/pull/7050#discussion_r873113836
##########
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.
|
Review Comment:
```suggestion
| unhealthy.http_statuses | array[integer] | False | [500] | [500, ...,
599] | Status codes of Upstream to be considered unhealthy.
|
```
##########
docs/en/latest/plugins/api-breaker.md:
##########
@@ -84,12 +78,14 @@ curl "http://127.0.0.1:9080/apisix/admin/routes/1"; -H
'X-API-KEY: edd1c9f034335f
}'
```
-## Test Plugin
+In this configuration, a response code of 500 or 503 three times in a row
triggers the unhealthy status of the Upstream service. A response code of 200
restores its healthy status.
+
+## Example usage
-Then. Like the configuration above, if your upstream service returns 500. 3
times in a row. The client will receive a 502 (break_response_code) response.
+Once you have configured the Plugin as show above, you can test it out by
sending a request. If the Upstream service responds with an unhealthy response
code, you will receive the configured response code (`break_response_code`).
Review Comment:
```suggestion
Once you have configured the Plugin as shown above, you can test it out by
sending a request. If the Upstream service responds with an unhealthy response
code, you will receive the configured response code (`break_response_code`).
```
##########
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.
|
Review Comment:
I would suggest using `[]` instead of `{}` :)
```suggestion
| healthy.http_statuses | array[integer] | False | [200] | [200, ...,
499] | Status codes of Upstream to be considered healthy.
|
```
##########
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.
|
Review Comment:
Two attributes are missing
1. break_response_body
2. break_response_headers
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
