structured-logging

JSON-structured logging patterns with correlation IDs, log levels, and contextual metadata for the FastAPI backend (structlog) and Next.js frontend (Logger class). Enforces consistent observability across the stack.

Aller à l'installation

Dépôt: CleanExpo/DR-NRPG
Dernière activité de la source: 4 mars 2026 à 14:17
Langue détectée de SKILL.md: anglais
Étoiles: 1
Forks: 0

Options d'installation

Le prompt qui vérifie d'abord la source est sélectionné par défaut. Vous pouvez passer à une commande directe ou télécharger une copie locale.

Vérifiez les fichiers source

Lisez SKILL.md et les fichiers associés affichés par SkillsMP avant de décider de l'installer.

Retour à la recherche Retour à l’installation

# GOOD: Structured with context
logger.info("Document created", document_id=doc.id, user_id=user.id)

# BAD: Unstructured string interpolation
logger.info(f"Document {doc.id} created by user {user.id}")

# BAD: print() for logging
print(f"Created doc: {doc.id}")

Level	When to Use	Example
ERROR	Operation failed, needs attention	Database connection lost, agent execution failed
WARNING	Recoverable issue, degraded behaviour	Rate limit approaching, fallback provider used
INFO	Significant business events	User logged in, document created, agent run completed
DEBUG	Development-only detail	Query parameters, intermediate computation results

from src.utils import get_logger

logger = get_logger(__name__)

# Logger name becomes the "logger" field in JSON output
# e.g., "logger": "src.api.routes.documents"

import uuid
import structlog
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request


class CorrelationIdMiddleware(BaseHTTPMiddleware):
    """Attach a correlation ID to every request for log tracing."""

    async def dispatch(self, request: Request, call_next):
        correlation_id = request.headers.get(
            "X-Correlation-ID",
            str(uuid.uuid4())
        )

        # Bind to structlog context (available to all loggers in this request)
        structlog.contextvars.clear_contextvars()
        structlog.contextvars.bind_contextvars(
            correlation_id=correlation_id,
        )

        response = await call_next(request)
        response.headers["X-Correlation-ID"] = correlation_id
        return response

from .middleware.correlation import CorrelationIdMiddleware

app.add_middleware(CorrelationIdMiddleware)

import time
from src.utils import get_logger

logger = get_logger(__name__)


class RequestLoggingMiddleware(BaseHTTPMiddleware):
    """Log request method, path, status, and duration."""

    async def dispatch(self, request: Request, call_next):
        start = time.perf_counter()
        response = await call_next(request)
        duration_ms = (time.perf_counter() - start) * 1000

        logger.info(
            "Request completed",
            method=request.method,
            path=request.url.path,
            status=response.status_code,
            duration_ms=round(duration_ms, 2),
        )
        return response

logger = get_logger(__name__)


async def execute_agent(agent_name: str, task: str):
    logger.info("Agent started", agent=agent_name, task=task[:100])

    try:
        result = await agent.run(task)
        logger.info(
            "Agent completed",
            agent=agent_name,
            status="success",
            duration_ms=result.duration_ms,
        )
        return result
    except TimeoutError:
        logger.error(
            "Agent timed out",
            agent=agent_name,
            error_code="AGENT_RUNTIME_TIMEOUT",
        )
        raise
    except Exception as exc:
        logger.error(
            "Agent failed",
            agent=agent_name,
            error_code="AGENT_RUNTIME_FAILED",
            error=str(exc),
        )
        raise

{
  "timestamp": "2026-02-13T09:30:00.000Z",
  "level": "info",
  "event": "Request completed",
  "logger": "src.api.middleware.logging",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "method": "POST",
  "path": "/api/documents",
  "status": 201,
  "duration_ms": 42.5
}

import { logger } from '@/lib/logger';

// Business events
logger.info('Document created', { documentId: doc.id, userId: user.id });

// Warnings
logger.warn('API response slow', { endpoint: '/api/agents', durationMs: 2500 });

// Errors (always include the error object)
logger.error('Failed to fetch documents', error, { userId: user.id });

// Debug (stripped in production via LOG_LEVEL)
logger.debug('API response', { status: response.status, body: data });

let correlationId: string | null = null;

export async function apiRequest(path: string, options?: RequestInit) {
  const headers: Record<string, string> = {
    'Content-Type': 'application/json',
    ...(correlationId ? { 'X-Correlation-ID': correlationId } : {}),
  };

  const response = await fetch(`${BACKEND_URL}${path}`, {
    ...options,
    headers: { ...headers, ...options?.headers },
  });

  // Capture correlation ID from response
  correlationId = response.headers.get('X-Correlation-ID');

  return response;
}

// BAD
console.log('User logged in');
console.error('Failed to load', error);

// GOOD
logger.info('User logged in', { userId: user.id });
logger.error('Failed to load', error, { component: 'Dashboard' });

Domain	Fields
API requests	`method`, `path`, `status`, `duration_ms`
Authentication	`user_id`, `action` (login/logout/token_refresh)
Agent execution	`agent`, `task` (truncated), `status`, `duration_ms`
Database operations	`table`, `operation` (select/insert/update/delete), `row_count`
External services	`service`, `endpoint`, `status`, `duration_ms`

Pattern	Problem	Correct Approach
Unstructured `log.info(f"User {id} logged in")` strings	Not machine-parseable, breaks log aggregation	Use structured key-value pairs: `logger.info("User logged in", user_id=id)`
Logging sensitive data (passwords, tokens, API keys)	Security breach via log exposure	Redact sensitive fields; never log credentials or session tokens
No correlation IDs across requests	Cannot trace a request through backend and frontend	Use `CorrelationIdMiddleware` and propagate `X-Correlation-ID` header
Inconsistent log levels (ERROR for warnings, INFO for debug)	Noisy alerts, missed critical errors	Follow the log level table: ERROR/WARNING/INFO/DEBUG
Using `console.log` instead of the Logger class	No level filtering, no structured context, no timestamps	Import `logger` from `@/lib/logger` and use its methods

[AGENT_ACTIVATED]: Structured Logging
[PHASE]: {Implementation | Review | Configuration}
[STATUS]: {in_progress | complete}

{logging analysis or implementation guidance}

[NEXT_ACTION]: {what to do next}

logger.error("Agent failed", error_code="AGENT_RUNTIME_FAILED", agent=name)