request-id.md

title	keywords	description
request-id	Apache APISIX API Gateway Request ID	This document describes information about the Apache APISIX request-id Plugin, you can use it to track API requests by adding a unique ID to each request.

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

Name	Type	Required	Default	Valid values	Description
header_name	string	False	"X-Request-Id"		Header name for the unique request ID.
include_in_response	boolean	False	true		When set to true, adds the unique request ID in the response header.
algorithm	string	False	"uuid"	["uuid", "snowflake", "nanoid", "range_id"]	Algorithm to use for generating the unique request ID.
range_id.char_set	string	False	"abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789	The minimum string length is 6	Character set for range_id
range_id.length	integer	False	16	Minimum 6	Id length for range_id algorithm

Using snowflake algorithm to generate unique ID

:::caution

• When you need to use snowflake algorithm, make sure APISIX has the permission to write to the etcd.
• Please read this documentation before deciding to use the snowflake algorithm. Once it is configured, you cannot arbitrarily change the configuration. Failure to do so may result in duplicate IDs.

:::

The snowflake algorithm supports flexible configurations to cover a variety of needs. Attributes are as follows:

Name	Type	Required	Default	Description
enable	boolean	False	false	When set to true, enables the snowflake algorithm.
snowflake_epoc	integer	False	1609459200000	Starting timestamp in milliseconds. Default is 2021-01-01T00:00:00Z and supports to a 69 year time until 2090-09-0715:47:35Z.
data_machine_bits	integer	False	12	Maximum number of supported machines (processes) 1 << data_machine_bits. Corresponds the set of workIDs and dataCenterIDs in the snowflake definition. Each process is associated to a unique ID. The maximum number of supported processes is pow(2, data_machine_bits). So, for the default value of 12 bits, it is 4096.
sequence_bits	integer	False	10	Maximum number of generated ID per millisecond per node 1 << sequence_bits. Each process generates up to 1024 IDs per millisecond.
data_machine_ttl	integer	False	30	Valid time in seconds of registration of data_machine in etcd.
data_machine_interval	integer	False	10	Time in seconds between data_machine renewals in etcd.

To use the snowflake algorithm, you have to enable it first on your configuration file conf/config.yaml:

plugin_attr:
  request-id:
    snowflake:
      enable: true
      snowflake_epoc: 1609459200000
      data_machine_bits: 12
      sequence_bits: 10
      data_machine_ttl: 30
      data_machine_interval: 10

Enabling the Plugin

The example below enables the Plugin on a specific Route:

curl http://127.0.0.1:9180/apisix/admin/routes/5 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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

Disable Plugin

To disable 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: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/get",
    "plugins": {
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:8080": 1
        }
    }
}'