Skip to main content
Version: 3.10

request-id

Description#

The request-id Plugin adds a unique ID to each request proxied through APISIX.

This Plugin can be used to track API requests.

note

The Plugin will not add a unique ID if the request already has a header with the configured header_name.

Attributes#

NameTypeRequiredDefaultValid valuesDescription
header_namestringFalse"X-Request-Id"Header name for the unique request ID.
include_in_responsebooleanFalsetrueWhen set to true, adds the unique request ID in the response header.
algorithmstringFalse"uuid"["uuid", "nanoid", "range_id"]Algorithm to use for generating the unique request ID.
range_id.char_setstringFalse"abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789The minimum string length is 6Character set for range_id
range_id.lengthintegerFalse16Minimum 6Id length for range_id algorithm

Enable Plugin#

The example below enables the Plugin on a specific Route:

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
curl http://127.0.0.1:9180/apisix/admin/routes/5 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/hello",
"plugins": {
"request-id": {
"include_in_response": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'

Example usage#

Once you have configured the Plugin as shown above, APISIX will create a unique ID for each request you make:

curl -i http://127.0.0.1:9080/hello
HTTP/1.1 200 OK
X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956

Delete Plugin#

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.

curl http://127.0.0.1:9180/apisix/admin/routes/5 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/get",
"plugins": {
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'