0
# ASGI Correlation ID
1

2
Middleware for reading or generating correlation IDs for each incoming request. Correlation IDs can then be added to your logs, making it simple to retrieve all logs generated from a single HTTP request. The middleware automatically detects correlation ID headers from incoming requests or generates new ones when none are present, then makes these IDs available throughout the request lifecycle for logging and tracing purposes.
3

4
## Package Information
5

6
- **Package Name**: asgi-correlation-id
7
- **Language**: Python  
8
- **Installation**: `pip install asgi-correlation-id`
9

10
## Core Imports
11

12
```python
13
from asgi_correlation_id import (
14
    CorrelationIdMiddleware,
15
    CorrelationIdFilter,
16
    CeleryTracingIdsFilter,
17
    correlation_id,
18
    celery_current_id,
19
    celery_parent_id,
20
)
21
```
22

23
For extensions:
24

25
```python
26
from asgi_correlation_id.extensions.celery import (
27
    load_correlation_ids,
28
    load_celery_current_and_parent_ids,
29
)
30
from asgi_correlation_id.extensions.sentry import (
31
    get_sentry_extension,
32
    set_transaction_id,
33
)
34
```
35

36
## Basic Usage
37

38
```python
39
from fastapi import FastAPI
40
from asgi_correlation_id import CorrelationIdMiddleware, CorrelationIdFilter
41
import logging
42

43
# Add middleware to your ASGI app
44
app = FastAPI()
45
app.add_middleware(CorrelationIdMiddleware)
46

47
# Configure logging with correlation ID filter
48
logging.basicConfig(
49
    level=logging.INFO,
50
    format='%(levelname)s [%(correlation_id)s] %(name)s %(message)s'
51
)
52

53
# Add the correlation ID filter to your logger
54
logger = logging.getLogger(__name__)
55
correlation_filter = CorrelationIdFilter()
56
logger.addFilter(correlation_filter)
57

58
@app.get("/")
59
async def root():
60
    logger.info("This log will include the correlation ID")
61
    return {"message": "Hello World"}
62
```
63

64
## Architecture
65

66
The library follows a layered architecture:
67

68
- **Middleware Layer**: `CorrelationIdMiddleware` intercepts requests, extracts or generates correlation IDs, and makes them available via context variables
69
- **Context Layer**: Thread-safe context variables (`correlation_id`, `celery_current_id`, `celery_parent_id`) store IDs throughout request/task lifecycle
70
- **Logging Layer**: Log filters (`CorrelationIdFilter`, `CeleryTracingIdsFilter`) automatically attach correlation IDs to log records
71
- **Extensions Layer**: Optional integrations with Celery for task correlation and Sentry for transaction tagging
72

73
This design enables seamless request tracing across async applications, background tasks, and external service integrations.
74

75
## Capabilities
76

77
### ASGI Middleware
78

79
Core middleware functionality for intercepting HTTP requests, extracting or generating correlation IDs, and making them available throughout the request lifecycle via context variables.
80

81
```python { .api }
82
class CorrelationIdMiddleware:
83
    def __init__(
84
        self,
85
        app,
86
        header_name: str = 'X-Request-ID',
87
        update_request_header: bool = True,
88
        generator: Callable[[], str] = lambda: uuid4().hex,
89
        validator: Optional[Callable[[str], bool]] = is_valid_uuid4,
90
        transformer: Optional[Callable[[str], str]] = lambda a: a
91
    ): ...
92
    
93
    async def __call__(self, scope, receive, send) -> None: ...
94

95
def is_valid_uuid4(uuid_: str) -> bool: ...
96
```
97

98
[ASGI Middleware](./middleware.md)
99

100
### Context Management
101

102
Context variables for storing and accessing correlation IDs throughout async request/task execution, providing thread-safe access to tracking identifiers.
103

104
```python { .api }
105
correlation_id: ContextVar[Optional[str]]
106
celery_parent_id: ContextVar[Optional[str]]  
107
celery_current_id: ContextVar[Optional[str]]
108
```
109

110
[Context Management](./context.md)
111

112
### Logging Integration
113

114
Log filters that automatically attach correlation IDs to log records, enabling seamless log correlation without manual ID injection.
115

116
```python { .api }
117
class CorrelationIdFilter(logging.Filter):
118
    def __init__(
119
        self,
120
        name: str = '',
121
        uuid_length: Optional[int] = None,
122
        default_value: Optional[str] = None
123
    ): ...
124
    
125
    def filter(self, record) -> bool: ...
126

127
class CeleryTracingIdsFilter(logging.Filter):
128
    def __init__(
129
        self,
130
        name: str = '',
131
        uuid_length: Optional[int] = None,
132
        default_value: Optional[str] = None
133
    ): ...
134
    
135
    def filter(self, record) -> bool: ...
136
```
137

138
[Logging Integration](./logging.md)
139

140
### Celery Extension
141

142
Integration with Celery for propagating correlation IDs from HTTP requests to background tasks, enabling end-to-end request tracing across async and task processing layers.
143

144
```python { .api }
145
def load_correlation_ids(
146
    header_key: str = 'CORRELATION_ID',
147
    generator: Callable[[], str] = uuid_hex_generator
148
) -> None: ...
149

150
def load_celery_current_and_parent_ids(
151
    header_key: str = 'CELERY_PARENT_ID',
152
    generator: Callable[[], str] = uuid_hex_generator,
153
    use_internal_celery_task_id: bool = False
154
) -> None: ...
155

156
uuid_hex_generator: Callable[[], str]
157
```
158

159
[Celery Extension](./celery-extension.md)
160

161
### Sentry Extension
162

163
Integration with Sentry SDK for tagging events with correlation IDs, enabling correlation between application logs and error monitoring.
164

165
```python { .api }
166
def get_sentry_extension() -> Callable[[str], None]: ...
167

168
def set_transaction_id(correlation_id: str) -> None: ...
169
```
170

171
[Sentry Extension](./sentry-extension.md)