title: request-id keywords:
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
.
:::
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 |
:::caution
snowflake
algorithm, make sure APISIX has the permission to write to the etcd.:::
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
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 } } }'
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
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 } } }'