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.

Zur Installation springen

Repository: CleanExpo/DR-NRPG
Letzte Quellaktivität: 4. März 2026 um 14:17
Erkannte Sprache von SKILL.md: Englisch
Sterne: 1
Forks: 0

Installationsoptionen

Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.

Quelldateien prüfen

Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.

Zurück zur Suche Zurück zur 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)