Observation
By semantically classifying all phenomena occurring during application runtime and recording them along with causes, severity, handling strategies, stakeholders, and technical contexts (such as trace information and execution environments), they can be consistently utilized for logging, monitoring, analysis, auditing, troubleshooting, alerting, and error reporting.
In SimpleModeling, those phenomena among “all phenomena” that are subject to recording are called observation records.
In the SimpleModeling Reference Profile, the object org.simplemodeling.observation.Observation is provided to describe observation records.
Purpose
Observation records are one of the central model elements in the medical domain, but in general modeling they have not been positioned as a generic, common model.
However, in cloud applications, observability features are becoming an essential foundation. Moreover, as an implementation technique, there are significant benefits in unifying and structuring logs, traces, notifications, alerts, and errors.
For this reason, SimpleModeling treats observation records as a generic, common model element and also materializes them as objects used in programming.
Phenomenon/Observation/Domain Event
Various occurrences in system operations or domain behavior are called “phenomena.”
Among them, those worth recording are observation records.
Among observation records, those that represent key aspects of system or domain behavior are modeled as events, and when modeled within the domain model, they are called domain events.
SimpleModeling deliberately distinguishes the hierarchy of “phenomenon / observation record / domain event.”
Constituent Elements
The structure of the org.simplemodeling.observation.Observation object introduced in SMRP is described below.
The Observation object is defined by the following attributes.
-
Semantic Information
-
Related Entities
-
Trace Information
-
Additional Information
Semantic Information
Semantic information is defined by attributes that describe the observed phenomenon.
- phenomenon
-
Observed event or phenomenon (e.g., Timeout, Failure)
- cause
-
Cause (e.g., ValidationError, NullPointer)
-
severity ::Severity level (e.g., INFO, WARN, ERROR, FATAL)
-
- strategy
-
Response strategy (e.g., Recoverable, Retriable, Escalatable)
- handler
-
Responsible party (e.g., EndUser, Developer)
Phenomenon
Phenomenon represents types of situations observed in the system or domain, indicating errors or abnormal conditions.
| Name | Description |
|---|---|
|
Failure |
A function fails to perform as expected |
|
Rejection |
An input or request is rejected |
|
Incident |
An unexpected event occurring during operation |
|
Deviation |
A deviation from baseline or specification |
Cause
CauseKind classifies the underlying reasons of a phenomenon.
| Name | Description |
|---|---|
|
Defect |
A flaw in design or implementation |
|
Fault |
An inherent fault within the system |
|
Anomaly |
An irregular or abnormal behavior |
|
Root Cause |
The fundamental underlying cause |
Severity
Severity indicates the seriousness and impact of a phenomenon.
| Name | Description |
|---|---|
|
Fatal |
A fatal issue that halts the entire system |
|
Error |
An error that prevents part of the system from functioning |
|
Warn |
Warning signs of anomaly, but operation continues |
|
Info |
Informational messages or minor events |
|
Debug |
Detailed data for debugging purposes |
|
Trace |
Low-level trace data of system execution |
Strategy
Strategy specifies how to respond when a phenomenon occurs.
| Name | Description |
|---|---|
|
Manual |
Requires manual intervention |
|
Recoverable |
Can be recovered automatically |
|
Retriable |
Retrying may resolve the issue |
|
Escalatable |
Escalated to higher-level personnel or systems |
|
Alert |
Triggers alerts or notifications |
|
Ignored |
Can be safely ignored |
Handler
Handler categorizes the parties responsible for handling a phenomenon.
| Name | Description |
|---|---|
|
EndUser |
Handled directly by the end user |
|
ApplicationAdmin |
Handled by the application administrator |
|
SystemAdmin |
Handled by the system administrator |
|
Developer |
Requires resolution by a developer |
Related Entities
Related entities are defined by attributes that specify the actors and resources associated with the phenomenon.
| Item | Description |
|---|---|
|
subject |
Actor (e.g., user, API client) |
|
object |
Target resource (e.g., order data, file) |
|
component |
Executing component (e.g., OrderService) |
|
location |
Execution environment (e.g., k8s node, region) |
Trace Information
Trace information is defined by attributes that integrate with external observability features such as distributed tracing.
| Item | Description |
|---|---|
|
traceId |
Trace ID for the entire request (supports distributed tracing) |
|
spanId |
Span ID representing an individual processing unit |
Additional Information
Additional information is defined by attributes that provide supplemental details to the observation record.
| Item | Description |
|---|---|
|
timestamp |
Time observed |
|
message |
Human-readable, i18n message |
|
exception |
Occurred exception (if any) |
|
properties |
Optional supplemental info (key/value) |
Related Works
Observation records have been discussed as analysis patterns in domains such as healthcare, but the concepts of observation records and domain events have drawn broader attention since the mid-2010s. This trend has largely been driven by the demands of cloud applications.
In SimpleModeling, we adopt an approach that integrates modeling techniques for phenomena, observation records, and domain events with observability, though at present this may be considered a unique approach.
UML
-
The Unified Modeling Language (UML) User Guide 2nd (2005)
-
The Unified Modeling Language Reference Manual 2nd (2005)
UML does not define the concepts of phenomena or observation records. Events are defined as components of the behavioral mechanisms in dynamic models.
Analysis Patterns
-
Analysis Patterns : Elements of Reusable Object-Oriented Software (1997)
In Analysis Patterns, phenomena and observation records are described in detail as patterns within analysis models. Events, however, are not given a prominent definition.
Domain-Driven Design
-
Domain-Driven Design : Tackling Complexity in the Heart of Software (2004)
-
Implementing Domain-Driven Design (2013)
DDD focuses mainly on static models and does not address observation records. In its initial form, the concept of domain events is also absent.
In IDDD, while observation records are not mentioned, domain events are introduced as a key modeling element.
Software Architecture
-
Patterns of Enterprise Application Architecture (2003)
-
Enterprise Integration Patterns (2004)
-
Clean Architecture (2017)
In these works on software architecture, concepts such as phenomena, observation records, and domain events do not appear.
Observability
-
Observability Engineering: Achieving Production Excellence (2022)
This is one of the representative works on observability. Its main theme is the integration of logs, traces, and metrics in distributed applications, but the modeling of observation records and their continuity with domain events is outside its scope.
References
Glossary
- phenomenon
-
Phenomenon represents various occurrences within a domain. Among them, those worthy of being noted are stored as Observations. Furthermore, among observations, those that have meaning within the domain and trigger corresponding behaviors are modeled as Domain Events.
- error
-
A generic term used broadly in practice. In software engineering, it is ambiguous and may denote bugs or failures in general. In SimpleModeling, Error is treated as a broad label, with specifics clarified as Mistake, Defect, Fault, Failure, or Deviation.
- observation
-
Observation is the recorded form of phenomena that are judged worthy of being noted and stored. Observations serve as the foundation for logging, monitoring, auditing, and troubleshooting.
- SimpleModeling Reference Profile (SMRP)
-
This is the reference profile of SimpleModeling. To concretely illustrate Literate Model-Driven Development with SimpleModeling, a reference profile is defined.
- observability
-
Observability represents the property of a system or domain whereby its internal state can be inferred and understood through external observations. It goes beyond simple monitoring: by consistently collecting and correlating phenomena and observations, and interpreting them as domain events, observability enables a comprehensive understanding of system behavior.
- Domain Event
-
A Domain Event represents an observation that carries meaning within the domain and triggers corresponding behaviors or processes. Domain events explicitly model state changes in the system or business and drive interactions across application layers or with external systems.
- deviation
-
The state in which a computed or observed value differs from a baseline or true value. Represents a measurable quantitative discrepancy.
- fault
-
A manifestation of a defect within the system. A technical imperfection that, if encountered during execution, may cause a Failure. Defined in IEEE 610.12.
- defect
-
An imperfection or deficiency in a work product (designs, specifications, code, etc.). It does not meet requirements or specifications and requires repair or replacement. Defined in ISO/IEC 24765.
- Component
-
A software construct that encapsulates well-defined responsibilities, contracts, and dependencies as a reusable and replaceable unit. In the logical model, it serves as an abstract structural unit; in the physical model, it corresponds to an implementation or deployment unit.
- UML (Unified Modeling Language)
-
A standardized modeling language for object-oriented analysis and design. It represents system structures and behaviors through diagrams such as class, sequence, and use case diagrams. Serves as the foundational language for UP and CBD.