Overview

When an unhandled exception or latency spike occurs in a high-concurrency asynchronous web server, diagnosing the root cause across interleaved log streams is notoriously difficult. Without a unique correlation identifier attached to every log record, engineers are forced to stitch together fragmented timestamps across hundreds of simultaneous concurrent operations.

loglens solves this challenge by leveraging native Python contextvars to propagate correlation IDs and request context seamlessly across all asyncio tasks, background coroutines, and framework boundaries with zero external core dependencies.

---

Context Propagation Across Async Boundaries

Traditional thread-local storage (threading.local) completely fails in asyncio applications because thousands of concurrent coroutines share the same operating system thread.

loglens utilizes contextvars.ContextVar, which guarantees that:

• Every incoming HTTP request is assigned a unique correlation_id (or inherits one from incoming headers such as X-Request-ID or traceparent).
• Any sub-task or coroutine spawned via asyncio.create_task or asyncio.gather automatically inherits the parent’s execution context.
• Log handlers enrich log records with the active correlation identifier, elapsed duration, and contextual fields without manual parameter passing.

import loglens
import logging

logger = logging.getLogger("service")

# Setup structured logging in production or developer mode
loglens.setup_production()

@app.get("/orders/{order_id}")
async def handle_order(order_id: int):
    logger.info("Processing order request", extra={"order_id": order_id})
    # Any background tasks spawned here automatically inherit the same correlation ID
    asyncio.create_task(sync_inventory(order_id))
    return {"status": "accepted"}

---

Automatic Secret Redaction

Accidentally leaking sensitive credentials, session tokens, or API secrets into log aggregators (e.g., Datadog, Elasticsearch, CloudWatch) represents a catastrophic security vulnerability and compliance violation.

loglens includes an automatic redaction engine enabled by default:

• Known Header and Key Redaction: Common authentication headers and dictionary keys (Authorization, password, secret, token, api_key, access_token) are sanitized automatically.
• Pattern-Based Scrubbing: High-entropy patterns such as Bearer tokens, JSON Web Tokens (JWTs), and SSH private keys are detected and masked ([REDACTED]) before formatting.

---

Ready-to-Use ASGI and WSGI Middleware

loglens includes drop-in middleware for both FastAPI (Starlette) and aiohttp:

• Extracts incoming correlation headers or generates high-entropy cryptographic UUIDs.
• Emits structured access logs containing request path, method, status code, IP address, and total processing duration in milliseconds.
• Injects X-Correlation-ID into outgoing HTTP response headers for immediate client-side trace correlation.