Observability

Metrics (Prometheus / OTel metrics)

Expose /metrics endpoint. Track RED (Rate, Errors, Duration) per endpoint + per pipeline stage:

• http_requests_total{route,method,status}
• http_request_duration_seconds{route} (histogram, SLO buckets)
• pipeline_stage_duration_seconds{stage}
• pipeline_stage_errors_total{stage,error_type}
• extraction_entities_total{label}
• normalization_cache_hits_total{vocab}

SLOs (soft targets for portfolio demo)

• /v1/extract p95 < 2000ms for notes ≤ 2KB.
• Error rate < 1% over rolling 1h.

Runbook integration

Every alert has a link to a section in docs/runbook.md with "likely causes" and "what to check."

What's banned

• Log-and-swallow (except Exception: logger.error(...)). Log, enrich, re-raise.
• String-formatted log messages that hide structure.
• Logging full request bodies by default. Opt-in per debug flag.
• Metrics with unbounded label cardinality (never label by user ID or note ID).