ADR-011-OBSERVABILITY-BY-DESIGN

ADR-011 – Überwachbarkeit by Design#

Status#

Accepted

Context#

During EP-002.2, role-based visibility and user-personalization behaviour could not be diagnosed reliably from the rendered interface. The system did not expose which interaction arrived, which policy decision was made, which ⌘relationshipEine Beziehung beschreibt eine nachvollziehbare Verbindung zwischen Bedeutungen, Artefakten und ihrem Kontext. applied or which context transition triggered rendering.

Simple diagnostic log text was insufficient because it could not reliably connect the observed behaviour with Execution Context, architecture ⌘meaningBedeutung beschreibt den fachlichen Sinn eines Elements und seine Relevanz für Menschen und Organisationen., decision, state transition and resulting ⌘EvidenceTechnical documentation artifact..

Decision#

Observability and Explainability are mandatory cross-cutting architecture capabilities.

Every materialized component provides suitable structured observations, tracing, diagnostics, health or Evidence from its first usable version. Meaningful decisions and state transitions are correlated with their Execution Context and affected architecture artifacts where practical.

The common log levels are ERROR, WARN, INFO, DEBUG and TRACE. Log detail is configurable without source changes. Sensitive information is excluded.

Stable technical Reason identities remain language-neutral. Human-readable explanations and remediation guidance are localizable.

Consequences#

• Systems become easier to verify, diagnose and evolve.
• Implementations define observable events and safe log data as part of their contracts and tests.
• Successful decisions and fallbacks are observable, not only failures.
• Evidence can reference the rules, Decisions and artifacts that explain an outcome.
• Solutions choose their telemetry and persistence technologies without redefining the Enterprise semantics.
• Observability data is not retained without purpose; privacy, confidentiality and proportionality remain mandatory constraints.

Related Architecture#

• ◆Observability by DesignVerlangt beobachtbare und erklärbare Actions, Decisions, State Transitions und Results. – decides
• ◆Execution Context and Event ModelDefiniert Execution als zeitliche Interpretation der Ontologie in einem konkreten Kontext. – related-to
• Systems must explain themselves – explained-by