ASGI request id middleware
Project description
asgi-request-id 🌟
asgi-request-id
is a middleware for ASGI applications that provides a unique request identifier for each incoming request. This identifier can be used for logging, tracing, and debugging purposes, making it easier to track requests as they flow through your application. The middleware is highly configurable, allowing you to customize the request ID generation, specify headers for incoming and outgoing request IDs, and exclude certain paths from request ID handling. It is compatible with popular ASGI frameworks like Starlette and FastAPI, and can be easily integrated into your existing application with minimal changes.
Table of Contents 📚
Installation 📦
pip install asgi-request-id
Usage 🚀
The asgi-request-id
middleware performs the following actions:
- Searches for an incoming request identifier using the
incoming_request_id_header
attribute and uses it as the request ID if found. - Generates a unique request ID with an optional prefix if no incoming request identifier is found.
- Stores the request ID in a context variable, making it accessible to the logging context through a filter.
- Includes the request ID in the response headers. If the
outgoing_request_id_header
attribute is set, its value will be used as the response header name. Ensure that the chosen header name complies with HTTP header naming conventions.
For Python 3.6 compatibility, install the backported contextvars package.
Middleware 🛠️
The RequestIdMiddleware
class is used to handle the request ID header. It has the following attributes:
app
: The ASGI application.excluded_paths
: List of paths to exclude from middleware processing.incoming_request_id_header
: Optional incoming request ID header.outgoing_request_id_header
: Optional outgoing request ID header.prefix
: Optional prefix to add to the request ID.skip_validate_header_name
: Optional flag to skip header name validation.uuid_generator
: Optional UUID generator.
Example 🔍
Here is a minimal example demonstrating how to use the asgi-request-id
middleware. Additional examples with more detailed use cases and configurations can be found in the examples
folder of the repository.
import os
import uvicorn
from asgi_request_id import RequestIdMiddleware
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route
from uuid import uuid4
async def info_endpoint(request: Request) -> JSONResponse:
return JSONResponse({"message": "info"})
async def excluded_endpoint(request: Request) -> JSONResponse:
return JSONResponse({"message": "excluded"})
routes = [
Route("/info", info_endpoint, methods=["GET"]),
Route("/excluded", excluded_endpoint, methods=["GET"]),
]
app = Starlette(routes=routes)
app.add_middleware(
RequestIdMiddleware,
excluded_paths=["/excluded"],
incoming_request_id_header="x-request-id",
outgoing_request_id_header="x-request-id",
prefix="my-special-prefix-",
uuid_generator=lambda: uuid4().hex,
)
if __name__ == "__main__":
log_config = f"{os.path.dirname(__file__)}{os.sep}conf{os.sep}logging.yaml"
config = uvicorn.Config("app:app", host="127.0.0.1", port=8000, log_config=log_config)
server = uvicorn.Server(config)
server.run()
Logging 📝
To integrate the request ID into your logging, you can use the RequestIdFilter
class. Here is an example logging.yaml
configuration:
---
version: 1
filters:
request_id:
(): 'asgi_request_id.RequestIdFilter'
default_value: '-'
formatters:
default:
(): 'uvicorn.logging.DefaultFormatter'
fmt: '%(levelprefix)s [%(asctime)s] %(message)s'
access:
(): 'uvicorn.logging.AccessFormatter'
fmt: '%(levelprefix)s [%(asctime)s] {%(request_id)s} %(client_addr)s - "%(request_line)s" %(status_code)s'
handlers:
default:
class: logging.StreamHandler
formatter: default
stream: ext://sys.stderr
access:
class: logging.StreamHandler
filters: [request_id]
formatter: access
stream: ext://sys.stdout
loggers:
uvicorn:
level: INFO
handlers:
- default
uvicorn.error:
level: INFO
uvicorn.access:
level: INFO
propagate: False
handlers:
- access
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file asgi_request_id-1.0.0.tar.gz
.
File metadata
- Download URL: asgi_request_id-1.0.0.tar.gz
- Upload date:
- Size: 8.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.2 CPython/3.11.5 Darwin/23.6.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
b1555094199f92d394a856902a5e70ba388b84df9164e31b4f0df022fe01a45d
|
|
MD5 |
127a5b7f1d022b22baad7d5fb94211aa
|
|
BLAKE2b-256 |
20edfd68a10ab8982a0aea9b283aaa5e707b7fb6580f91ad251247f63677421d
|
File details
Details for the file asgi_request_id-1.0.0-py3-none-any.whl
.
File metadata
- Download URL: asgi_request_id-1.0.0-py3-none-any.whl
- Upload date:
- Size: 8.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.2 CPython/3.11.5 Darwin/23.6.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
f7fd8387ce0b517fc86da86e3e9006595a59f5dffc73a365dfbee22995cfbf1d
|
|
MD5 |
c7ffaa2a9d99bb169d941d4eb4b12605
|
|
BLAKE2b-256 |
99ad663254d416654dec5b6cc9ec148920d7de48b963868c7432daac8c2b2b23
|