Skip to main content

ADR 034: Logging Rules for Platform Components

Date: 2026-03-10

Status: In Review

Decision Makers: CIVITAS/CORE Architecture Board

Context​

CIVITAS/CORE consists of multiple platform components that are deployed independently and interact through APIs and event-driven integration. To operate such a platform effectively, logs from different components must be collected, correlated, filtered, and analyzed in a consistent way.

Without common logging rules, operations and troubleshooting become unnecessarily difficult:

  • log messages use inconsistent formats and field names
  • correlation across component boundaries is unreliable
  • log levels are interpreted differently by each team
  • sensitive data may accidentally be written to logs
  • central observability tooling becomes less useful

Since ADR 011 establishes Grafana as the observability dashboard, the platform needs a shared logging baseline that works well with centralized log collection and later analysis in the observability stack.

Checked Architecture Principles​

  • [partial] Model-centric data flow
  • [full] Distributed architecture with unified user experience
  • [full] Modular design
  • [full] Integration capability through defined interfaces
  • [full] Open source as the default
  • [full] Cloud-native architecture
  • [full] Prefer standard solutions over custom development
  • [full] Self-contained deployment
  • [full] Technological consistency to ensure maintainability
  • [partial] Multi-tenancy
  • [full] Security by design

Comments on partial ratings:

  • Model-centric data flow: Logging is an operational concern, not a domain model concern, but standardized log fields improve traceability of model-driven workflows.
  • Multi-tenancy: Tenant-related context can be logged where appropriate, but tenant isolation still depends on the broader deployment and authorization model.

Decision​

All CIVITAS/CORE platform components must follow a common structured logging baseline.

The baseline rules are:

  • Logs are written to stdout and stderr; components do not rely on local log files as the primary operational interface.
  • Structured log output in JSON is preferred for machine processing and central collection.
  • Each log entry should contain at least timestamp, severity, component or service name, and a stable message.
  • Request IDs, correlation IDs, event IDs, tenant IDs, and user context should be included where available and appropriate.
  • Secrets, tokens, passwords, and other sensitive payload data must not be logged.
  • Log levels must be used consistently:
    • ERROR for failed operations requiring attention
    • WARN for unexpected situations that do not stop processing
    • INFO for relevant lifecycle and business-significant events
    • DEBUG only for diagnostic information that is normally disabled in production
  • Components should emit logs that support distributed tracing and event-based troubleshooting across service boundaries.

Consequences​

  • Platform teams can aggregate and analyze logs more reliably across all components.
  • Operational dashboards and alerting become easier to build because field names and severity usage are more consistent.
  • Component teams must invest in proper logger configuration, context propagation, and sensitive-data redaction.
  • Free-form ad hoc logging becomes less acceptable because it reduces the value of centralized observability.
  • Log governance must be part of code reviews and operational readiness checks.

Alternatives​

  • Component-specific logging styles: Rejected because it makes cross-component troubleshooting and central observability unnecessarily hard.
  • Plain text logs without structure: Rejected as default because parsing and correlation are more brittle in a distributed platform.
  • Local file-based logging as the primary mechanism: Rejected because it does not fit the platform's cloud-native operating model.

See also​

  • ADR 011: Select Observability Dashboard