Version: Next

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. 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"]	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.
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:

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):

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:

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:

X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441

Send a request to the Route with a custom request ID in the header:

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:

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:

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:

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:

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:

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:

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:

{
  "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:

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:

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:

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:

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:

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:

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:

Global-Request-ID: 2e9b99c1-08ed-4a74-b347-49c0891b07ad
Route-Request-ID: d755666b-732c-4f0e-a30e-a7a71ace4e26

Description#

Attributes#

Examples#

note

Attach Request ID to Default Response Header#

Attach Request ID to Custom Response Header#

Hide Request ID in Response Header#

Use nanoid Algorithm#

Attach Request ID Globally and on a Route#

Use `nanoid` Algorithm#