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.

request-id - 图1note

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”, “snowflake”, “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

Using snowflake algorithm to generate unique ID

request-id - 图2caution
  • 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:

NameTypeRequiredDefaultDescription
enablebooleanFalsefalseWhen set to true, enables the snowflake algorithm.
snowflake_epocintegerFalse1609459200000Starting 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_bitsintegerFalse12Maximum 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_bitsintegerFalse10Maximum number of generated ID per millisecond per node 1 << sequence_bits. Each process generates up to 1024 IDs per millisecond.
data_machine_ttlintegerFalse30Valid time in seconds of registration of data_machine in etcd.
data_machine_intervalintegerFalse10Time 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:

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

Enabling the Plugin

The example below enables the Plugin on a specific Route:

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

Example usage

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

  1. curl -i http://127.0.0.1:9080/hello
  1. HTTP/1.1 200 OK
  2. 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.

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