Minimum Observability Ontology¶

The Minimum Observability Ontology defines the smallest stable semantic model required to connect services, telemetry, runtime resources, dependencies, and operational signals.

It sits above the canonical mappings and provides a common conceptual model for the observability platform.

The ontology is intentionally small.

It does not attempt to model every OpenTelemetry attribute, Prometheus label, Grafana panel, or instrumentation detail. Those belong in the Metrics Catalogue, OTel Fields and Attributes, Field Matrix, and Canonical Mappings.

Purpose¶

The ontology provides a stable semantic layer for answering questions such as:

Which service produced this telemetry?
Which environment is the service running in?
Which instance produced the signal?
Which request generated this trace?
Which span represents the operation?
Which dependency did the service interact with?
Which database operation occurred?
Which log belongs to which trace or span?
Which metric describes the service or its runtime?
Which infrastructure resource is being observed?

The ontology therefore describes entities and relationships, not individual telemetry fields.

Ontology Scope¶

The minimum ontology contains the following concepts:

Service
Service Instance
Environment
Host
Process
Telemetry Signal
Trace
Span
Log Record
Metric
Dependency
Database
External Service
Runtime

These concepts are sufficient to connect the current dashboards and telemetry signals without introducing unnecessary domain complexity.

Core Concepts¶

Service¶

A logical application or service producing telemetry.

Examples:

data-quality-service
recommendation-service
api-gateway

Canonical identifier:

observability.service

Important properties:

service name
service version
environment

A Service may have multiple Service Instances.

Service Instance¶

A running instance of a Service.

A Service Instance represents one execution instance rather than the logical service itself.

Examples:

data-quality-service instance A
data-quality-service instance B

Canonical identifier:

observability.service_instance

Important properties:

instance ID
process ID
host
runtime
service

A Service Instance belongs to exactly one Service.

Environment¶

The deployment environment in which a Service Instance operates.

Examples:

development
staging
production

Canonical identifier:

observability.environment

A Service Instance operates in one Environment at a given point in time.

Host¶

The machine or compute environment hosting a Service Instance.

Important properties include:

host name
architecture
operating system

Canonical identifier:

observability.host

A Host may run multiple Service Instances.

Process¶

The operating system process executing a Service Instance.

Important properties include:

process ID
runtime
runtime version
start time

Canonical identifier:

observability.process

A Process belongs to a Service Instance.

Runtime¶

The language runtime in which a Process executes.

Examples:

CPython
JVM
Node.js

Canonical identifier:

observability.runtime

The current implementation primarily exposes Python runtime information.

Telemetry Concepts¶

Telemetry Signal¶

A piece of observability data emitted by a Service or Service Instance.

The current system supports three primary signal types:

Metric
Log Record
Trace

Canonical identifier:

observability.telemetry_signal

A Telemetry Signal is produced by a Service Instance.

Metric¶

A numerical telemetry signal representing a measurement or state.

Examples:

request duration
CPU utilization
memory usage
GC collections
network I/O

Canonical identifier:

observability.metric

Metrics may describe:

a Service
a Service Instance
a Process
a Database
an external dependency
the underlying system

The metric definition itself belongs in the Metrics Catalogue.

Trace¶

A distributed execution record representing a request or operation across service boundaries.

Canonical identifier:

observability.trace

A Trace contains one or more Spans.

A Trace is associated with the Service or Services involved in the execution.

Span¶

A unit of work within a Trace.

Examples:

HTTP Request
SQL Query
Redis GET
HTTP Client Request
Authentication

Canonical identifier:

observability.span

A Span may:

belong to a Trace
have a parent Span
represent an operation
interact with a Dependency
have a status
have a duration

The Span hierarchy provides the execution path used by the Traces dashboard.

Log Record¶

A structured or unstructured log event emitted during application execution.

Canonical identifier:

observability.log_record

A Log Record may be associated with:

a Service
a Service Instance
a Trace
a Span

The current logging implementation provides trace and span correlation.

Dependency Concepts¶

Dependency¶

A system or component that a Service interacts with to perform work.

Canonical identifier:

observability.dependency

Dependencies may include:

Database
Redis
External Service
Internal Service

The Dependency concept provides a common parent for downstream systems without requiring every dependency type to become a separate top-level ontology concept.

Database¶

A persistent data system accessed by a Service.

Examples:

PostgreSQL
MySQL

Canonical identifier:

observability.database

Database operations appear as Metrics or Spans.

External Service¶

A service accessed over a network by the observed Service.

Examples:

payment provider
third-party API
internal microservice

Canonical identifier:

observability.external_service

HTTP client instrumentation provides telemetry describing interactions with these services.

Relationships¶

The minimum ontology is primarily defined by the following relationships:

Environment
    ↑
operates_in
    |
Service Instance
    |
    ├── instance_of ──→ Service
    |
    ├── runs_on ──────→ Host
    |
    └── executes ─────→ Process
                            |
                            └── uses ──→ Runtime


Service Instance
    |
    └── produces ─────→ Telemetry Signal
                            |
                            ├── Metric
                            ├── Log Record
                            └── Trace


Trace
    |
    └── contains ─────→ Span
                            |
                            ├── parent_of ──→ Span
                            |
                            └── interacts_with ──→ Dependency
                                                     |
                                                     ├── Database
                                                     └── External Service


Log Record
    |
    ├── belongs_to ───→ Trace
    |
    └── belongs_to ───→ Span


Metric
    |
    └── describes ────→ Observable Resource

Relationship Catalogue¶

Relationship	Source	Target	Meaning
`instance_of`	Service Instance	Service	Instance belongs to a logical service
`operates_in`	Service Instance	Environment	Instance runs in an environment
`runs_on`	Service Instance	Host	Instance executes on a host
`executes`	Service Instance	Process	Instance is represented by a process
`uses`	Process	Runtime	Process executes using a runtime
`produces`	Service Instance	Telemetry Signal	Instance emits telemetry
`contains`	Trace	Span	Trace contains spans
`parent_of`	Span	Span	Span represents a parent operation
`interacts_with`	Span	Dependency	Span represents interaction with a dependency
`associated_with`	Log Record	Trace	Log is correlated with a trace
`associated_with`	Log Record	Span	Log is correlated with a span
`describes`	Metric	Observable Resource	Metric describes a runtime or service resource

Observable Resource¶

Metrics require one additional abstraction.

A metric does not necessarily describe a Service directly.

For example:

CPU utilization
    → Process

Memory usage
    → Process

GC collections
    → Runtime

Request duration
    → Service / HTTP Request

Database operation duration
    → Database Operation

Therefore the ontology introduces:

Observable Resource

Canonical identifier:

observability.observable_resource

This is an abstract concept used to connect metrics to the thing being measured.

It does not require every resource to become an independent ontology entity.

Telemetry Relationships¶

The central telemetry model can therefore be represented as:

Service
   │
   └── Service Instance
          │
          ├── Process
          │     └── Runtime
          │
          └── produces
                 │
                 ├── Metrics
                 │
                 ├── Log Records
                 │       │
                 │       ├── Trace
                 │       └── Span
                 │
                 └── Traces
                         │
                         └── Spans
                               │
                               └── Dependencies
                                      │
                                      ├── Database
                                      └── External Service

This structure is sufficient to connect the current dashboards.

Dashboard Coverage¶

Dashboard	Ontology Concepts Used
Service Overview	Service, Service Instance, Environment, Metric
Infrastructure	Service Instance, Host, Process, Runtime, Metric
HTTP/API	Service, Service Instance, Metric
Database	Service, Span, Database, Dependency, Metric
External Services	Service, Span, External Service, Dependency, Metric
Logs	Service, Service Instance, Log Record, Trace, Span
Traces	Service, Service Instance, Trace, Span, Dependency

Mapping to Canonical IDs¶

The ontology consumes canonical identifiers rather than implementation specific metric names.

Examples:

service.name
    ↓
observability.service.name
    ↓
observability.service


service.instance.id
    ↓
observability.service.instance.id
    ↓
observability.service_instance


deployment.environment
    ↓
observability.environment
    ↓
observability.environment


trace_id
    ↓
observability.trace.id
    ↓
observability.trace


span_id
    ↓
observability.span.id
    ↓
observability.span

The mapping therefore follows:

OTel Field
    ↓
Canonical ID
    ↓
Ontology Concept

What Is Deliberately Not in the Minimum Ontology¶

The following are intentionally excluded from the first version:

Dashboard
Panel
PromQL Query
LogQL Query
Grafana
Jaeger
Prometheus
Loki
OpenTelemetry Collector
Instrumentation Library
Alert
SLO
Incident
Business KPI
Team
User
Customer
Deployment Pipeline
Container
Pod
Kubernetes Cluster
Cloud Provider

These may become useful later, but they are not necessary to represent the current observability model.

In particular, implementation systems such as Grafana, Jaeger, Prometheus, and Loki belong to the implementation architecture rather than the semantic ontology.

Future Extensions¶

The ontology can be extended when the observability implementation demonstrates a genuine need.

Potential future concepts include:

Container
Pod
Node
Cluster
Deployment
Queue
Job
Message
Alert
Incident
SLO
Business Metric
LLM Request
LLM Model
Token Usage

These should only be introduced when they represent stable concepts required by the telemetry model or dashboards.

Minimum Stable Model¶

The minimum stable observability ontology is therefore:

Service
Service Instance
Environment
Host
Process
Runtime

Telemetry Signal
Metric
Trace
Span
Log Record

Dependency
Database
External Service

Observable Resource

with the following core relationships:

Service
    ← instance_of ← Service Instance
Service Instance
    → operates_in → Environment
Service Instance
    → runs_on → Host
Service Instance
    → executes → Process
Process
    → uses → Runtime
Service Instance
    → produces → Telemetry Signal
Trace
    → contains → Span
Span
    → parent_of → Span
Span
    → interacts_with → Dependency
Log Record
    → associated_with → Trace
Log Record
    → associated_with → Span
Metric
    → describes → Observable Resource

This is deliberately the smallest model capable of representing the current observability system without turning the ontology into a duplicate of the field matrix or metrics catalogue.