blob: 3592135fd6948eb9ae5a048aa2ba96696e0f0e66 [file] [log] [blame] [view]
---
title: request-id
keywords:
- Apache APISIX
- API Gateway
- Request ID
description: 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.
---
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->
## 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`:
```yaml title="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:
```shell
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:
```shell
curl -i http://127.0.0.1:9080/hello
```
```shell
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.
```shell
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
}
}
}'
```