ADR-050: Structured JSON logging

Category: development Provenance: human

Decision

Use structured logging with JSON output format. Every log entry is valid JSON with consistent fields.

Rationale

JSON logs are machine-parseable. Log aggregation systems (ELK, Loki) can index and search JSON fields. Correlation IDs link related log entries across reconciliation cycles. Structured context (namespace, resource name) enables filtering. Consistent format across all logs simplifies tooling. Better than parsing plain text logs. Enables advanced queries and dashboards in log analysis tools.

Agent Instructions

Configure Python logging to output JSON using structlog or similar. Include standard fields: timestamp, level, message, logger name, correlation IDs, resource info (namespace, name, kind). See src/keycloak_operator/observability/logging.py. Never use plain text logging. Add context fields for filtering and analysis.

Rejected Alternatives

Plain text logging

Hard to parse. Can't reliably extract fields. Log analysis requires complex regex. Doesn't scale.

Multiple log formats

Inconsistent. Each format requires different parsers. Makes log aggregation harder.