asgi-correlation-id

What it is and what it does

This package provides ASGI middleware that attaches a unique correlation ID to each incoming HTTP request, either by reading an existing ID from a header (like X-Request-ID or X-Correlation-ID) or by generating a new one. The middleware stores this ID in a way that makes it accessible to your application's logging system, allowing you to tag all log messages from a single request with the same ID.

The primary use case is request tracing: when logs from different parts of your application are all tagged with the same correlation ID, you can easily retrieve and correlate all logs belonging to a single user request. The package integrates with Python's standard logging module via a filter and supports customization of header names, ID generation, validation, and transformation.

Use it for:

• Debugging production issues by filtering logs to show only those from a specific user request.
• Tracing requests across multiple services when correlation IDs are propagated through HTTP headers.
• Integrating with error tracking services to group errors by the request that triggered them.
• Auditing and compliance logging where you need to track all actions during a specific request.
• Correlating logs from multiple handlers or middleware layers processing the same incoming request.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

ASGI middleware that reads or generates correlation IDs for incoming requests and makes them available to logging, enabling you to trace all logs from a single HTTP request.

Yes. The package is production-stable (Development Status 5), has no known vulnerabilities, minimal dependencies, and solves a common observability problem in ASGI applications. Install it if you need to correlate logs across your application; the setup overhead is low and the debugging value is high.

Install

asgi-correlation-id on PyPI

pip install asgi-correlation-id

uv add asgi-correlation-id

poetry add asgi-correlation-id

Installing asgi-correlation-id

Before you install

Low friction: pure Python wheel with a single runtime dependency on starlette. Actively maintained with recent releases; last commit 2026-06-09 and 638 repository stars indicate steady adoption and support.

License in practice

MIT license (permissive) places no restrictions on use, modification, or distribution in commercial or private projects.

Quickstart

pip install asgi-correlation-id

from asgi_correlation_id import CorrelationIdMiddleware
from starlette.applications import Starlette

app = Starlette()
app.add_middleware(CorrelationIdMiddleware)

# Configure logging to include %(correlation_id)s in format string

Requires Python 3.10 or later; logging must be configured separately to include correlation_id in the format string.

Verify before relying

• Performance overhead of correlation ID generation and storage per request under high throughput.
• Compatibility with async context propagation in complex middleware stacks beyond Starlette.
• Whether correlation IDs propagate correctly through background tasks or worker processes.

Package facts

Evidence: asgi_correlation_id-5.0.1-py3-none-any.whl

Keywords: asgi, fastapi, starlette, async, correlation, correlation-id, request-id, x-request-id, tracing, logging, middleware, sentry

Tags

More Software Development packages