OBSERVABILITY-BY-DESIGN

Überwachbarkeit by Design#

Principle#

Every materialized system must make important actions, decisions, context changes, state transitions and outcomes observable from its first usable version.

Observability is not limited to errors. Successful interactions, policy decisions, execution phases, deployments and verification results must also be observable and explainable.

Enterprise scope#

The principle applies to enterprise, solution, platform, building-block, runtime and deployment architecture. The concrete telemetry technology is selected by the respective Solution.

Required characteristics#

• structured observations with defined levels or categories;
• traceable actions, decisions and state-transition events;
• correlation with Execution Context and affected architecture artifacts;
• health, diagnostics and ⌘evidenceTechnical documentation artifact. appropriate to the component;
• configurable detail without source changes;
• no passwords, credentials, tokens or unnecessary personal data;
• stable technical identities for important reasons and outcomes;
• localizable human-readable explanations;
• explicit distinction between observation, Evidence and Learning.

Observability and Explainability#

Observability answers:

• What happened?
• When and in which Context did it happen?
• Which state changed?
• What result was observed?

Explainability additionally answers:

• Why did it happen?
• Which ⌘MeaningBedeutung beschreibt den fachlichen Sinn eines Elements und seine Relevanz für Menschen und Organisationen., ⌘RelationshipEine Beziehung beschreibt eine nachvollziehbare Verbindung zwischen Bedeutungen, Artefakten und ihrem Kontext., rule, policy or Decision applied?
• Which Reason identifies the outcome?
• Which Evidence supports the explanation?

A log line is not automatically Evidence, and Evidence is not automatically Learning. These transitions require purpose, ⌘provenanceProvenienz beschreibt die nachvollziehbare Herkunft eines Wissenselements, einer Aussage oder einer abgeleiteten Darstellung. and evaluation.

Core relation#

Action
                → Decision
                → State Transition
                → Observable Event
                → Evidence
                → Explanation

Reason identities#

Stable Reason Codes may be used as technical identities, for example for missing permissions, invalid contributions or fallback selections. Reason Codes are not translated. Their human-readable explanations, remediation hints and help references must be localizable.

The Enterprise Architecture defines this separation but not a concrete Reason-Code catalog.

Rule#

A system that cannot expose and explain its meaningful behaviour cannot be reliably engineered, verified or evolved.

Related Architecture#

• ◆Execution Context and Event ModelDefiniert Execution als zeitliche Interpretation der Ontologie in einem konkreten Kontext. – derived-from
• ◆Execution Evidence ModelOrdnet Engineering Execution und Evidence als Spezialisierung der universellen Enterprise-Execution ein. – realized-through
• ◆ADR-011Beschließt Observability und Explainability als verpflichtende Querschnittsfähigkeiten. – decided-by
• Systems must explain themselves – explained-by