Context Management

Context variables for storing and accessing correlation IDs throughout async request and task execution, providing thread-safe access to tracking identifiers across the entire application lifecycle.

Capabilities

Request Correlation ID

Context variable that stores the correlation ID for the current HTTP request, making it accessible throughout the request processing lifecycle.

correlation_id: ContextVar[Optional[str]]

This context variable:

• Default Value: None
• Scope: HTTP request lifecycle
• Thread Safety: Automatically isolated per async context
• Usage: Set by middleware, accessed by logging filters and application code

The correlation_id is automatically set by CorrelationIdMiddleware and remains available throughout the entire request processing, including:

• Route handlers and business logic
• Database operations and external API calls
• Background tasks spawned during request processing
• Log statements and error handling

Celery Parent ID

Context variable that tracks the correlation ID of the parent process that spawned the current Celery task, enabling hierarchical tracing across distributed task processing.

celery_parent_id: ContextVar[Optional[str]]

This context variable:

• Default Value: None
• Scope: Celery task execution
• Purpose: Track which process/request spawned the current task
• Usage: Set by Celery extension hooks, accessed by logging filters

Use cases for parent ID tracking:

• Tracing task chains and workflows back to originating requests
• Understanding task dependency hierarchies
• Correlating distributed task processing with web requests
• Debugging complex async workflows

Celery Current ID

Context variable that stores a unique identifier for the current Celery task process, providing task-specific correlation tracking.

celery_current_id: ContextVar[Optional[str]]

This context variable:

• Default Value: None
• Scope: Celery task execution
• Purpose: Unique identifier for the current task process
• Usage: Set by Celery extension hooks, accessed by logging filters

The current ID can be:

• Generated UUID for each new task (default behavior)
• Celery's internal task ID (when use_internal_celery_task_id=True)
• Custom ID from configured generator function

Usage Examples

Accessing Correlation ID in Application Code

from asgi_correlation_id import correlation_id
import logging

logger = logging.getLogger(__name__)

async def process_data(data):
    # Get current correlation ID
    current_id = correlation_id.get()
    
    if current_id:
        logger.info(f"Processing data for request {current_id}")
    else:
        logger.info("Processing data outside request context")
    
    # Process data...
    return result

Manual Context Management

from asgi_correlation_id import correlation_id

async def background_task():
    # Set correlation ID for background processing
    correlation_id.set("background-task-123")
    
    # Process task...
    logger.info("Background task processing")  # Will include correlation ID
    
    # Clear when done (optional, context will be cleaned up automatically)
    correlation_id.set(None)

Celery Task Context

from asgi_correlation_id import celery_current_id, celery_parent_id
from celery import Celery

app = Celery('tasks')

@app.task
def process_task(data):
    current = celery_current_id.get()
    parent = celery_parent_id.get()
    
    logger.info(f"Task {current} spawned by {parent}")
    
    # Process task...
    return result

Context Variable Behavior

Automatic Cleanup

Context variables are automatically managed:

• HTTP Requests: Cleaned up when request completes
• Celery Tasks: Manually cleaned up by extension hooks
• Background Tasks: Follow async context rules

Thread Safety

All context variables use Python's contextvars module, providing:

• Automatic isolation between concurrent requests
• Inheritance by spawned async tasks
• Thread-safe access patterns
• No manual synchronization required

Inheritance

Context variables are inherited by:

• Async tasks spawned during request processing
• Celery tasks when properly configured with extensions
• Background threads created with contextlib.copy_context()

Types

from contextvars import ContextVar
from typing import Optional

# Context variable type definitions
CorrelationIdVar = ContextVar[Optional[str]]
CeleryParentIdVar = ContextVar[Optional[str]]  
CeleryCurrentIdVar = ContextVar[Optional[str]]