Skip to content

Latest commit

 

History

History
137 lines (110 loc) · 7.18 KB

request-id.md

File metadata and controls

137 lines (110 loc) · 7.18 KB
Raw
title keywords description
request-id
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"] Algorithm to use for generating the unique request ID.

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
        }
    }
}'