Yilialinn commented on code in PR #11931: URL: https://github.com/apache/apisix/pull/11931#discussion_r1980873760
########## docs/en/latest/plugins/request-id.md: ########## @@ -61,54 +59,238 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Attach Request ID to Default Response Header + +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to the default `X-Request-Id` response header, if the header value is not passed in the request. When the `X-Request-Id` header is set in the request, the Plugin will take the value in the request header as the request ID. + +Create a Route with the `request-id` Plugin using its default configurations (explicitly defined): + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/5 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/hello", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", "plugins": { - "request-id": { - "include_in_response": true - } + "request-id": { + "header_name": "X-Request-Id", + "include_in_response": true, + "algorithm": "uuid" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:8080": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +Send a request to the route: Review Comment: ```suggestion Send a request to the Route: ``` ########## docs/en/latest/plugins/request-id.md: ########## @@ -61,54 +59,238 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Attach Request ID to Default Response Header + +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to the default `X-Request-Id` response header, if the header value is not passed in the request. When the `X-Request-Id` header is set in the request, the Plugin will take the value in the request header as the request ID. + +Create a Route with the `request-id` Plugin using its default configurations (explicitly defined): + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/5 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/hello", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", "plugins": { - "request-id": { - "include_in_response": true - } + "request-id": { + "header_name": "X-Request-Id", + "include_in_response": true, + "algorithm": "uuid" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:8080": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +Send a request to the route: + +```shell +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Request-Id` header with a generated ID: + +```text +X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441 +``` + +Send a request to the Route with a custom request ID in the header: + +```shell +curl -i "http://127.0.0.1:9080/anything"; -H 'X-Request-Id: some-custom-request-id' +``` + +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Request-Id` header with the custom request ID: + +```text +X-Request-Id: some-custom-request-id ``` -## Example usage +### Attach Request ID to Custom Response Header -Once you have configured the Plugin as shown above, APISIX will create a unique ID for each request you make: +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to a specified header. + +Create a Route with the `request-id` Plugin to define a custom header that carries the request ID and include the request ID in the response header: ```shell -curl -i http://127.0.0.1:9080/hello +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", + "plugins": { + "request-id": { + "header_name": "X-Req-Identifier", + "include_in_response": true + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' ``` +Send a request to the route: + ```shell -HTTP/1.1 200 OK -X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956 +curl -i "http://127.0.0.1:9080/anything"; ``` -## Delete Plugin +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Req-Identifier` header with a generated ID: + +```text +X-Req-Identifier: 1c42ff59-ee4c-4103-a980-8359f4135b21 +``` + +### Hide Request ID in Response Header + +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to a specified header. The header containing the request ID should be forwarded to the Upstream service but not returned in the response header. + +Create a Route with the `request-id` Plugin to define a custom header that carries the request ID and not include the request ID in the response header: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", + "plugins": { + "request-id": { + "header_name": "X-Req-Identifier", + "include_in_response": false + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` -To remove the `request-id` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Send a request to the route: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/5 \ --H "X-API-KEY: $admin_key" -X PUT -d ' +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should receive an `HTTP/1.1 200 OK` response not and see `X-Req-Identifier` header among the response headers. In the response body, you should see: + +```json { - "uri": "/get", + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.6.0", + "X-Amzn-Trace-Id": "Root=1-6752748c-7d364f48564508db1e8c9ea8", + "X-Forwarded-Host": "127.0.0.1", + "X-Req-Identifier": "268092bc-15e1-4461-b277-bf7775f2856f" + }, + ... +} +``` + +This shows the request ID is forwarded to the Upstream service but not returned in the response header. + +### Use `nanoid` Algorithm + +The following example demonstrates how to configure `request-id` on a Route and use the `nanoid` algorithm to generate the request ID. + +Create a Route with the `request-id` Plugin as such: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", "plugins": { + "request-id": { + "algorithm": "nanoid" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:8080": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to the route: + +```shell +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Req-Identifier` header with an ID generated using the `nanoid` algorithm: + +```text +X-Request-Id: kepgHWCH2ycQ6JknQKrX2 +``` + +### Attach Request ID Globally and on a Route + +The following example demonstrates how to configure `request-id` as a global Plugin and on a Route to attach two IDs. + +Create a global rule for the `request-id` Plugin which adds request ID to a custom header: + +```shell +curl -i "http://127.0.0.1:9180/apisix/admin/global_rules"; -X PUT -d '{ + "id": "rule-for-request-id", + "plugins": { + "request-id": { + "header_name": "Global-Request-ID" } + } }' ``` + +Create a Route with the `request-id` Plugin which adds request ID to a different custom header: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", + "plugins": { + "request-id": { + "header_name": "Route-Request-ID" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to the route: Review Comment: ```suggestion Send a request to the Route: ``` ########## docs/en/latest/plugins/request-id.md: ########## @@ -61,54 +59,238 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Attach Request ID to Default Response Header + +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to the default `X-Request-Id` response header, if the header value is not passed in the request. When the `X-Request-Id` header is set in the request, the Plugin will take the value in the request header as the request ID. + +Create a Route with the `request-id` Plugin using its default configurations (explicitly defined): + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/5 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/hello", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", "plugins": { - "request-id": { - "include_in_response": true - } + "request-id": { + "header_name": "X-Request-Id", + "include_in_response": true, + "algorithm": "uuid" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:8080": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +Send a request to the route: + +```shell +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Request-Id` header with a generated ID: + +```text +X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441 +``` + +Send a request to the Route with a custom request ID in the header: + +```shell +curl -i "http://127.0.0.1:9080/anything"; -H 'X-Request-Id: some-custom-request-id' +``` + +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Request-Id` header with the custom request ID: + +```text +X-Request-Id: some-custom-request-id ``` -## Example usage +### Attach Request ID to Custom Response Header -Once you have configured the Plugin as shown above, APISIX will create a unique ID for each request you make: +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to a specified header. + +Create a Route with the `request-id` Plugin to define a custom header that carries the request ID and include the request ID in the response header: ```shell -curl -i http://127.0.0.1:9080/hello +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", + "plugins": { + "request-id": { + "header_name": "X-Req-Identifier", + "include_in_response": true + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' ``` +Send a request to the route: + ```shell -HTTP/1.1 200 OK -X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956 +curl -i "http://127.0.0.1:9080/anything"; ``` -## Delete Plugin +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Req-Identifier` header with a generated ID: + +```text +X-Req-Identifier: 1c42ff59-ee4c-4103-a980-8359f4135b21 +``` + +### Hide Request ID in Response Header + +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to a specified header. The header containing the request ID should be forwarded to the Upstream service but not returned in the response header. + +Create a Route with the `request-id` Plugin to define a custom header that carries the request ID and not include the request ID in the response header: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", + "plugins": { + "request-id": { + "header_name": "X-Req-Identifier", + "include_in_response": false + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` -To remove the `request-id` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Send a request to the route: Review Comment: ```suggestion Send a request to the Route: ``` ########## docs/en/latest/plugins/request-id.md: ########## @@ -61,54 +59,238 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Attach Request ID to Default Response Header + +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to the default `X-Request-Id` response header, if the header value is not passed in the request. When the `X-Request-Id` header is set in the request, the Plugin will take the value in the request header as the request ID. + +Create a Route with the `request-id` Plugin using its default configurations (explicitly defined): + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/5 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/hello", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", "plugins": { - "request-id": { - "include_in_response": true - } + "request-id": { + "header_name": "X-Request-Id", + "include_in_response": true, + "algorithm": "uuid" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:8080": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +Send a request to the route: + +```shell +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Request-Id` header with a generated ID: + +```text +X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441 +``` + +Send a request to the Route with a custom request ID in the header: + +```shell +curl -i "http://127.0.0.1:9080/anything"; -H 'X-Request-Id: some-custom-request-id' +``` + +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Request-Id` header with the custom request ID: + +```text +X-Request-Id: some-custom-request-id ``` -## Example usage +### Attach Request ID to Custom Response Header -Once you have configured the Plugin as shown above, APISIX will create a unique ID for each request you make: +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to a specified header. + +Create a Route with the `request-id` Plugin to define a custom header that carries the request ID and include the request ID in the response header: ```shell -curl -i http://127.0.0.1:9080/hello +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", + "plugins": { + "request-id": { + "header_name": "X-Req-Identifier", + "include_in_response": true + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' ``` +Send a request to the route: + ```shell -HTTP/1.1 200 OK -X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956 +curl -i "http://127.0.0.1:9080/anything"; ``` -## Delete Plugin +You should receive an `HTTP/1.1 200 OK` response and see the response includes the `X-Req-Identifier` header with a generated ID: + +```text +X-Req-Identifier: 1c42ff59-ee4c-4103-a980-8359f4135b21 +``` + +### Hide Request ID in Response Header + +The following example demonstrates how to configure `request-id` on a Route which attaches a generated request ID to a specified header. The header containing the request ID should be forwarded to the Upstream service but not returned in the response header. + +Create a Route with the `request-id` Plugin to define a custom header that carries the request ID and not include the request ID in the response header: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", + "plugins": { + "request-id": { + "header_name": "X-Req-Identifier", + "include_in_response": false + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` -To remove the `request-id` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Send a request to the route: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/5 \ --H "X-API-KEY: $admin_key" -X PUT -d ' +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should receive an `HTTP/1.1 200 OK` response not and see `X-Req-Identifier` header among the response headers. In the response body, you should see: + +```json { - "uri": "/get", + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.6.0", + "X-Amzn-Trace-Id": "Root=1-6752748c-7d364f48564508db1e8c9ea8", + "X-Forwarded-Host": "127.0.0.1", + "X-Req-Identifier": "268092bc-15e1-4461-b277-bf7775f2856f" + }, + ... +} +``` + +This shows the request ID is forwarded to the Upstream service but not returned in the response header. + +### Use `nanoid` Algorithm + +The following example demonstrates how to configure `request-id` on a Route and use the `nanoid` algorithm to generate the request ID. + +Create a Route with the `request-id` Plugin as such: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "request-id-route", + "uri": "/anything", "plugins": { + "request-id": { + "algorithm": "nanoid" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:8080": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to the route: Review Comment: ```suggestion Send a request to the Route: ``` -- 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]
