Registry / observability / starlette-request-id

starlette-request-id

library1.2.1pypypi✓ verified 80d ago

A Starlette middleware that adds a unique request ID to each incoming request, typically used for logging and tracing. Current version 1.2.1 with a release cadence of occasional updates. Requires Python >=3.7.

observability web-framework

pip install starlette-request-id

github ↗package ↗

INSTALL

IMPORT

SIG · STARLETTE-REQUEST-

starlette-request-id

observabilitypythonv1.2.1

Install

2.1s avg

Import

—

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 20.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.1s · import 0.000s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RequestIdMiddleware

✓ from starlette_request_id import RequestIdMiddleware

✗ from starlette_request_id import RequestIDMiddleware

request_id_ctx

✓ from starlette_request_id import request_id_ctx

REQUEST_ID_HEADER

✓ from starlette_request_id import REQUEST_ID_HEADER

A minimal Starlette app that adds request ID middleware and returns the ID in the response.

from starlette.applications import Starlette from starlette.routing import Route from starlette.requests import Request from starlette.responses import JSONResponse from starlette_request_id import RequestIDMiddleware async def home(request: Request): request_id = request.headers.get('X-Request-ID') return JSONResponse({'request_id': request_id}) app = Starlette(debug=True, routes=[Route('/', home)]) app.add_middleware(RequestIDMiddleware) if __name__ == '__main__': import uvicorn uvicorn.run(app, host='0.0.0.0', port=8000)

Debug

Known issues

gotchaThe middleware automatically adds a request ID header, but it does not override an existing one from the client unless explicitly configured. By default, if the incoming request already has a 'X-Request-ID' header, that value is used instead of generating a new one. This can be surprising if you expect a fresh ID for every request.

fix

To force generation of a new ID regardless, pass force_new_uuid=True to the middleware constructor: app.add_middleware(RequestIDMiddleware, force_new_uuid=True).

affects: all

deprecatedThe attribute 'request.id' used in some older examples is deprecated. Use the 'X-Request-ID' header or the middleware's provided property instead.

fix

Access the request ID via request.headers.get('X-Request-ID') or the middleware's helper function.

affects: >=1.0.0

gotchaThe middleware must be added before any other middleware that might read request headers, otherwise the request ID might not be available in those middlewares.

fix

Add the RequestIDMiddleware as the first middleware in your application.

affects: all

Upgrade

Version history

1.2.1latest on PyPI · released Oct 19, 2024

Audit

Dependencies

starletterequiredCore dependency for middleware integration

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bigbag/starlette-request-id ↗

packagehttps://pypi.org/project/starlette-request-id/ ↗