ADR-049: Error Visibility — error_type Discriminator and X-Request-Id Convention

Date: 2026-04-06 Status: Implemented Deciders: Development Team Related: ADR-015 (Observability Stack)

Context

All 11 services emit structured JSON logs via the shared logger. Grafana/Loki is deployed (ADR-015) but no dashboard existed specifically for error diagnosis. Operators had no way to distinguish user-input errors (4xx) from system failures (5xx) without reading raw log lines. End-users had no reference ID to attach to bug reports.

Decision

1. Add error_type: 'user_error' | 'system_error' to LogContext and LogEntry. Set automatically by requestLoggingMiddleware based on response status code. Written as a JSON field; LogQL filters it with | json | error_type="system_error".

2. Set X-Request-Id response header on every HTTP response, echoing the requestId generated by requestLoggingMiddleware. Frontend captures it on 5xx errors.

3. Provision a Grafana error dashboard (error-visibility.json) with 5 panels: error rate by service, rate over time, recent system errors, recent user errors, errors with request IDs.

4. Frontend ErrorBoundary in _app.tsx surfaces refId (from axios-captured X-Request-Id) when a 5xx error reaches the render tree.

Consequences

• Every 4xx/5xx response is now tagged and queryable in Grafana without per-endpoint instrumentation.
• Users can reference a request ID when reporting errors.
• No DB schema changes, no new endpoints, no external services required.
• All 11 services benefit automatically — the shared logger is the single change point.