---
id: asgi-correlation-id
version: "5.0.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# asgi-correlation-id — Middleware correlating project logs to individual requests

License: permissive · Maintenance: active · Downloads: 6.9M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

asgi correlation id middleware, request tracing logging, correlation id header middleware, starlette request tracking, http request id logging, distributed request tracing, x-request-id middleware, observability, request-tracing, logging-integration

[View on SkillFed](https://skillfed.io/packages/asgi-correlation-id) · [View on PyPI](https://pypi.org/project/asgi-correlation-id/)