request-id

Description

request-id plugin adds a unique ID (UUID) to each request proxied through APISIX. This plugin can be used to track an API request. The plugin will not add a request id if the header_name is already present in the request.

Attributes

NameTypeRequirementDefaultValidDescription
header_namestringoptional“X-Request-Id”Request ID header name
include_in_responsebooleanoptionaltrueOption to include the unique request ID in the response header
algorithmstringoptional“uuid”[“uuid”, “snowflake”, “nanoid”]ID generation algorithm

How To Enable

Create a route and enable the request-id plugin on the route:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "uri": "/hello",
  4.     "plugins": {
  5.         "request-id": {
  6.             "include_in_response": true
  7.         }
  8.     },
  9.     "upstream": {
  10.         "type": "roundrobin",
  11.         "nodes": {
  12.             "127.0.0.1:8080": 1
  13.         }
  14.     }
  15. }'

Test Plugin

  1. $ curl -i http://127.0.0.1:9080/hello
  2. HTTP/1.1 200 OK
  3. X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956
  4. ......

Use the snowflake algorithm to generate an ID

supports using the Snowflake algorithm to generate ID. read the documentation first before deciding to use snowflake. Because once the configuration information is enabled, you can not arbitrarily adjust the configuration information. Failure to do so may result in duplicate ID being generated.

The Snowflake algorithm is not enabled by default and needs to be configured in ‘conf/config.yaml’.

  1. plugin_attr:
  2.   request-id:
  3.     snowflake:
  4.       enable: true
  5.       snowflake_epoc: 1609459200000
  6.       data_machine_bits: 12
  7.       sequence_bits: 10
  8.       data_machine_ttl: 30
  9.       data_machine_interval: 10

Configuration parameters

NameTypeRequirementDefaultValidDescription
enablebooleanoptionalfalseWhen set it to true, enable the snowflake algorithm.
snowflake_epocintegeroptional1609459200000Start timestamp (in milliseconds)
data_machine_bitsintegeroptional12Maximum number of supported machines (processes) 1 << data_machine_bits
sequence_bitsintegeroptional10Maximum number of generated ID per millisecond per node 1 << sequence_bits
data_machine_ttlintegeroptional30Valid time of registration of ‘data_machine’ in ‘etcd’ (unit: seconds)
data_machine_intervalintegeroptional10Time between ‘data_machine’ renewal in ‘etcd’ (unit: seconds)
  • snowflake_epoc default start time is 2021-01-01T00:00:00Z, and it can support 69 year approximately to 2090-09-0715:47:35Z according to the default configuration
  • data_machine_bits corresponds to the set of workIDs and datacEnteridd in the snowflake definition. The plug-in aslocates a unique ID to each process. Maximum number of supported processes is pow(2, data_machine_bits). The default number of 12 bits is up to 4096.
  • sequence_bits defaults to 10 bits and each process generates up to 1024 ID per millisecond.

example

Snowflake supports flexible configuration to meet a wide variety of needs

  • Snowflake original configuration
  • Start time 2014-10-20 T15:00:00.000z, accurate to milliseconds. It can last about 69 years
  • supports up to 1024 processes
  • Up to 4096 ID per millisecond per process
  1. plugin_attr:
  2.   request-id:
  3.     snowflake:
  4.       enable: true
  5.       snowflake_epoc: 1413817200000
  6.       data_machine_bits: 10
  7.       sequence_bits: 12

Disable Plugin

Remove the corresponding json configuration in the plugin configuration to disable the request-id. APISIX plugins are hot-reloaded, therefore no need to restart APISIX.

  1. curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "uri": "/get",
  4.     "plugins": {
  5.     },
  6.     "upstream": {
  7.         "type": "roundrobin",
  8.         "nodes": {
  9.             "127.0.0.1:8080": 1
  10.         }
  11.     }
  12. }'