observability

observability

Covers the three pillars — logs, metrics, and traces — with practical patterns for the Python/FastAPI + Node/PM2 + Docker stack.

1) Structured logging with structlog (Python)

import structlog

structlog.configure(
    processors=[
        structlog.stdlib.add_log_level,
        structlog.stdlib.add_logger_name,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.StackInfoRenderer(),
        structlog.processors.JSONRenderer(),   # machine-parseable
    ],
    wrapper_class=structlog.stdlib.BoundLogger,
    context_class=dict,
    logger_factory=structlog.PrintLoggerFactory(),
)

log = structlog.get_logger()

# Bind context to a request
log = log.bind(request_id=req_id, domain=domain)
log.info("article_generated", word_count=1200, model="gpt-4o")
log.error("llm_timeout", retries=3, elapsed_ms=15000)

2) Structured logging in Node.js

// Minimal structured logger (no deps)
const log = (level, msg, ctx = {}) =>
  process.stdout.write(JSON.stringify({ ts: new Date().toISOString(), level, msg, ...ctx }) + '\n');

log('info',  'server_start', { port: 4401 });
log('error', 'cache_miss',   { key: 'status', latency_ms: 4500 });

3) FastAPI health endpoints

from fastapi import APIRouter
import psutil, time

router = APIRouter()
START = time.time()

@router.get("/health")
async def health():
    return {"status": "ok"}

@router.get("/health/ready")
async def ready(db: AsyncSession = Depends(get_db)):
    # Check every hard dependency
    try:
        await db.execute(text("SELECT 1"))
    except Exception as e:
        raise HTTPException(503, detail=f"db: {e}")
    return {"status": "ready", "uptime_s": round(time.time() - START)}

@router.get("/health/metrics")
async def metrics():
    return {
        "cpu_pct":    psutil.cpu_percent(interval=0.1),
        "mem_pct":    psutil.virtual_memory().percent,
        "disk_pct":   psutil.disk_usage("/").percent,
        "uptime_s":   round(time.time() - START),
    }