request-id

Adds a unique request ID header to requests and responses.

Category TrafficAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin request-idPriority 12015

What it does

request-id gives every request through the route an ID and writes it into the header named under Header name, X-Request-Id unless you change it. The backend receives the header, and with Include in response on, the client finds it on the answer too.

Algorithm picks how the ID is made, uuid unless you change it. Range ID and its two settings are read only when the algorithm is range_id, and the form draws them only then.

When to use it

• A client of the orders API reports a failed call, and support finds the request in the backend's log by the ID on the answer the client got.
• A backend that sorts its records by time and wants IDs that sort the same way, made with uuidv7.
• A short ID that fits a log column or a support ticket, made of hexadecimal characters with a set length.
• A backend that already reads a correlation header under a name of its own, written under Header name.

Not for a header with a fixed value of your own on every request — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying) or tracing one request across several services with spans — see zipkin (Sends traces to a Zipkin collector).

Set it up

Give every request a short hexadecimal id

Leave Header name at X-Request-Id, set Algorithm to range_id and fill Range ID as in the JSON below.

request-id · as the console saves it

{
  "header_name": "X-Request-Id",
  "algorithm": "range_id",
  "range_id": {
    "char_set": "0123456789abcdef",
    "length": 12
  }
}

Things to know

• Include in response — Left on, the answer carries the header: with X-Request-Id as the name, a request to the route is answered 200 with an X-Request-Id header.
• Header name — A name with a space, X Request Id, is refused when you save.
• Header name — A name made only of the characters this field takes can still be one the response already owns: Content-Length is stored without complaint and then fails every request through this object with 500.
• Char set — A set of fewer than six characters, abc for example, is refused when you save.
• Char set — Every character ends up in a header: a newline arrives as %0A, and a non-ASCII character is split into bytes, so the id is not what the alphabet spells.
• Length — A length below six, 5 for example, is refused when you save.
• Length — The id travels in a request header and a response header, so a very long one is refused by the upstream's own header limit rather than by the gateway.
• Length — With range_id, a character set of hexadecimal digits and a length of 12, every answer carries an X-Request-Id of twelve hex characters.
• AdviceKeep one header name across the routes of an environment, so the backends and the support team look for the ID in one place. A global rule carries one copy for every route; Where a plugin runs shows how it meets a route's own.

Settings

The fields as the console shows them, section by section. A field under “When … is …” is there only while that value is set.

Header nameheader_namestringdefault X-Request-Id

The header the ID is written to.

pattern

^([$]secret://.+|[$][Ee][Nn][Vv]://.+|[A-Za-z0-9!#$%&'*+.^`|~-]+)$

Include in responseinclude_in_responsebooleandefault true

Adds the header to the response as well as to the request.

Algorithmalgorithmstringdefault uuid

How the ID is made: a UUID, a time-ordered UUID, a KSUID, a NanoID or a range ID drawn from a character set.

one of ksuid, nanoid, range_id, uuid, uuidv7

When Algorithm is range_id

Range IDrange_idobjectdefault {"char_set":"abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789","length":16}

Char setrange_id.char_setstringdefault abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789

at least 6 characters

Lengthrange_id.lengthintegerdefault 16

at least 6

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.