You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/05/15 06:20:19 UTC
[GitHub] [apisix] juzhiyuan commented on a diff in pull request #7050: docs: update "Traffic" Plugin docs 2
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org