Skip to main content

ASGI request id middleware

Project description

PyPI - Downloads PyPI - License PyPI - Version PyPI - Python Version PyPI - Status Dependencies Last Commit

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

asgi_request_id-1.0.0.tar.gz (8.1 kB view details)

Uploaded Source

Built Distribution

asgi_request_id-1.0.0-py3-none-any.whl (8.4 kB view details)

Uploaded Python 3

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

Hashes for asgi_request_id-1.0.0.tar.gz
Algorithm Hash digest
SHA256 b1555094199f92d394a856902a5e70ba388b84df9164e31b4f0df022fe01a45d
MD5 127a5b7f1d022b22baad7d5fb94211aa
BLAKE2b-256 20edfd68a10ab8982a0aea9b283aaa5e707b7fb6580f91ad251247f63677421d

See more details on using hashes here.

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

Hashes for asgi_request_id-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f7fd8387ce0b517fc86da86e3e9006595a59f5dffc73a365dfbee22995cfbf1d
MD5 c7ffaa2a9d99bb169d941d4eb4b12605
BLAKE2b-256 99ad663254d416654dec5b6cc9ec148920d7de48b963868c7432daac8c2b2b23

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page