ADR 034: Logging Rules for Platform Components

Date: 2026-03-10 Status: Accepted

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 ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 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.

The logging structure is defined like this:

{
  "timestamp": "2026-03-31T14:23:07.412Z",
  "level": "INFO",
  "service": "portal-backend",
  "message": "dataset submitted",
  "request_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "tenant_id": "XXX-XXX",
  "user_id": "XXX-XXX",
  "context": {
    "event": "dataset_creation",
    "dataset_id": "XXX-XXX"
  },
  "error": {
    "type": "org.postgresql.util.PSQLException",
    "message": "Connection refused",
    "stack_trace": "org.postgresql.util.PSQLException: Connection refused\n\tat org.postgresql..."
  }
}

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: TenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform.-related context can be logged where appropriate, but tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. 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, tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. 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