| --- |
| title: request-id |
| keywords: |
| - Apache APISIX |
| - API Gateway |
| - Request ID |
| description: The request-id Plugin adds a unique ID to each request proxied through APISIX, which can be used to track API requests. |
| --- |
| |
| <!-- |
| # |
| # Licensed to the Apache Software Foundation (ASF) under one or more |
| # contributor license agreements. See the NOTICE file distributed with |
| # this work for additional information regarding copyright ownership. |
| # The ASF licenses this file to You under the Apache License, Version 2.0 |
| # (the "License"); you may not use this file except in compliance with |
| # the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| # |
| --> |
| |
| <head> |
| <link rel="canonical" href="https://docs.api7.ai/hub/request-id" /> |
| </head> |
| |
| ## Description |
| |
| The `request-id` Plugin adds a unique ID to each request proxied through APISIX, which can be used to track API requests. If a request carries an ID in the header corresponding to `header_name`, the Plugin will use the header value as the unique ID and will not overwrite with the automatically generated ID. |
| |
| ## Attributes |
| |
| | Name | Type | Required | Default | Valid values | Description | |
| | ------------------- | ------- | -------- | -------------- | ------------------------------- | ---------------------------------------------------------------------- | |
| | header_name | string | False | "X-Request-Id" | | Name of the header that carries the request unique ID. Note that if a request carries an ID in the `header_name` header, the Plugin will use the header value as the unique ID and will not overwrite it with the generated ID. | |
| | include_in_response | boolean | False | true | | If true, include the generated request ID in the response header, where the name of the header is the `header_name` value. | |
| | algorithm | string | False | "uuid" | ["uuid","nanoid","range_id","ksuid"] | Algorithm used for generating the unique ID. When set to `uuid` , the Plugin generates a universally unique identifier. When set to `nanoid`, the Plugin generates a compact, URL-safe ID. When set to `range_id`, the Plugin generates a sequential ID with specific parameters. When set to `ksuid`, the Plugin generates a sequential ID with timestamp and random number. | |
| | range_id | object | False | | | Configuration for generating a request ID using the `range_id` algorithm. | |
| | range_id.char_set | string | False | "abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789" | minimum length 6 | Character set used for the `range_id` algorithm. | |
| | range_id.length | integer | False | 16 | >=6 | Length of the generated ID for the `range_id` algorithm. | |
| |
| ## Examples |
| |
| The examples below demonstrate how you can configure `request-id` in different scenarios. |
| |
| :::note |
| |
| You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: |
| |
| ```bash |
| admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') |
| ``` |
| |
| ::: |
| |
| ### 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" -X PUT \ |
| -H "X-API-KEY: ${ADMIN_API_KEY}" \ |
| -d '{ |
| "id": "request-id-route", |
| "uri": "/anything", |
| "plugins": { |
| "request-id": { |
| "header_name": "X-Request-Id", |
| "include_in_response": true, |
| "algorithm": "uuid" |
| } |
| }, |
| "upstream": { |
| "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 |
| ``` |
| |
| ### Attach Request ID to Custom Response Header |
| |
| 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 "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 |
| 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 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 |
| } |
| } |
| }' |
| ``` |
| |
| 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 not and see `X-Req-Identifier` header among the response headers. In the response body, you should see: |
| |
| ```json |
| { |
| "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": { |
| "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 |
| ``` |
| |
| ### Use `ksuid` Algorithm |
| |
| The following example demonstrates how to configure `request-id` on a Route and use the `ksuid` 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": "ksuid" |
| } |
| }, |
| "upstream": { |
| "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 an ID generated using the `ksuid` algorithm: |
| |
| ```text |
| X-Request-Id: 325ghCANEKjw6Jsfejg5p6QrLYB |
| ``` |
| |
| If the [ksuid](https://github.com/segmentio/ksuid?tab=readme-ov-file#command-line-tool) is installed, this ID can be viewed through `ksuid -f inspect 325ghCANEKjw6Jsfejg5p6QrLYB`: |
| |
| ``` text |
| REPRESENTATION: |
| |
| String: 325ghCANEKjw6Jsfejg5p6QrLYB |
| Raw: 15430DBBD7F68AD7CA0AE277772AB36DDB1A3C13 |
| |
| COMPONENTS: |
| |
| Time: 2025-09-01 16:39:23 +0800 CST |
| Timestamp: 356715963 |
| Payload: D7F68AD7CA0AE277772AB36DDB1A3C13 |
| ``` |
| |
| ### 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: |
| |
| ```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 following headers: |
| |
| ```text |
| Global-Request-ID: 2e9b99c1-08ed-4a74-b347-49c0891b07ad |
| Route-Request-ID: d755666b-732c-4f0e-a30e-a7a71ace4e26 |
| ``` |
