Canonical Mappings¶

This document defines the canonical observability identifiers used to provide a stable semantic layer over OpenTelemetry fields, Prometheus metric families, log fields, and tracing fields.

The purpose of canonical mappings is to prevent dashboards and downstream consumers from becoming tightly coupled to framework specific or exporter specific names.

For example, a Prometheus label such as http_status_code and an OTel attribute representing the HTTP response status may originate from different instrumentation implementations, but both can map to the same canonical concept.

The canonical identifier represents the meaning of the field, not its implementation specific name.

Mapping Principles¶

Canonical mappings follow these principles:

Canonical IDs represent meaning, not implementation.
OTel field names remain the source field names.
Prometheus metric names and labels are implementation representations of observability data.
Multiple implementation fields may map to the same canonical concept where their semantics are equivalent.
A canonical concept should not be created merely because two fields have similar names. Their semantics must be equivalent.
Canonical IDs should remain stable even when instrumentation libraries or exporters change.
Dashboard queries should ultimately depend on canonical concepts rather than implementation specific terminology where practical.

Canonical ID Structure¶

Canonical identifiers use the following structure:

observability.<domain>.<concept>

Examples:

observability.service.name
observability.http.request.duration
observability.http.request.status
observability.database.operation.duration
observability.trace.id
observability.log.severity

The identifier describes the semantic concept rather than the OTel representation.

Resource Mappings¶

Canonical ID	OTel Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.service.name`	`service.name`	Resource Attribute	string	Resource	direct	stable	Logical name of the service producing the telemetry
`observability.service.version`	`service.version`	Resource Attribute	string	Resource	direct	stable	Version of the deployed service
`observability.service.instance.id`	`service.instance.id`	Resource Attribute	string	Resource	direct	stable	Unique identifier for a running service instance
`observability.environment`	`deployment.environment`	Resource Attribute	string	Resource	direct	stable	Deployment environment in which the service is running
`observability.host.name`	`host.name`	Resource Attribute	string	Resource	direct	stable	Host on which the service process is running
`observability.host.architecture`	`host.arch`	Resource Attribute	string	Resource	direct	stable	Host CPU architecture
`observability.os.type`	`os.type`	Resource Attribute	string	Resource	direct	stable	Operating system type
`observability.process.id`	`process.pid`	Resource Attribute	integer	Resource	direct	stable	Process identifier
`observability.runtime.name`	`process.runtime.name`	Resource Attribute	string	Resource	direct	stable	Runtime implementation
`observability.runtime.version`	`process.runtime.version`	Resource Attribute	string	Resource	direct	stable	Runtime version

HTTP Server Mappings¶

HTTP server metrics describe requests entering the service.

Canonical ID	OTel / Prometheus Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.http.request.duration`	`http_server_duration_milliseconds`	Metric	numeric	Server Request	direct	stable	Duration of an incoming HTTP request
`observability.http.request.method`	`http_method`	Metric Label	string	Server Request	direct	stable	HTTP method used by the request
`observability.http.request.status`	`http_status_code`	Metric Label	integer	Server Request	direct	stable	HTTP response status code
`observability.http.request.target`	`http_target`	Metric Label	string	Server Request	direct	stable	HTTP request target
`observability.http.request.active`	`http_server_active_requests`	Metric	numeric	Server Request	direct	stable	Number of currently active HTTP requests

HTTP Client Mappings¶

HTTP client fields describe outbound HTTP requests made by the service.

Canonical ID	OTel / Prometheus Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.http.client.request.duration`	`http_client_request_duration`	Metric	numeric	Client Request	direct	stable	Duration of an outbound HTTP request
`observability.http.client.request.method`	`http_request_method`	Metric Label	string	Client Request	direct	stable	HTTP method used for the outbound request
`observability.http.client.response.status`	`http_response_status_code`	Metric Label	integer	Client Request	direct	stable	HTTP response status returned by the downstream service
`observability.http.client.server.address`	`server_address`	Metric Label	string	Client Request	direct	stable	Address of the downstream HTTP server
`observability.http.client.request.active`	`http_client_active_requests`	Metric	numeric	Client Request	direct	stable	Number of active outbound HTTP requests

Database Mappings¶

Database fields describe operations performed against database systems.

Canonical ID	OTel / Prometheus Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.database.operation.duration`	`db_client_operation_duration`	Metric	numeric	Database Operation	direct	stable	Duration of a database operation
`observability.database.operation.name`	`db_operation`	Metric Label	string	Database Operation	direct	stable	Database operation being performed
`observability.database.system`	`db_system_name`	Metric Label	string	Database Operation	direct	stable	Database system used by the operation
`observability.database.name`	`db_name`	Metric Label	string	Database Operation	direct	stable	Database name associated with the operation
`observability.database.operation.active`	`db_client_operation_active`	Metric	numeric	Database Operation	direct	stable	Number of active database operations
`observability.database.connection.usage`	`db_client_connections_usage`	Metric	numeric	Database Connection	direct	stable	Current database connection usage
`observability.database.connection.wait_time`	`db_client_connections_wait_time`	Metric	numeric	Database Connection	direct	stable	Time spent waiting for a database connection

Redis Mappings¶

Redis operations are represented using the database operation semantic domain because Redis is an external data store rather than a separate application telemetry category.

Canonical ID	OTel / Prometheus Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.database.operation.duration`	`db_client_operation_duration`	Metric	numeric	Redis Operation	direct	stable	Duration of a Redis operation
`observability.database.operation.name`	`db_operation`	Metric Label	string	Redis Operation	direct	stable	Redis operation being performed
`observability.database.system`	`db_system_name`	Metric Label	string	Redis Operation	direct	stable	Redis database system
`observability.database.operation.active`	`db_client_operation_active`	Metric	numeric	Redis Operation	direct	stable	Number of active Redis operations

Process and Runtime Mappings¶

Canonical ID	OTel / Prometheus Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.process.cpu.utilization`	`process_cpu_utilization_ratio`	Metric	ratio	Process	direct	stable	CPU utilization of the service process
`observability.process.cpu.time`	`process_cpu_time_seconds_total`	Metric	seconds	Process	direct	stable	Cumulative CPU time consumed by the process
`observability.process.memory.usage`	`process_memory_usage_bytes`	Metric	bytes	Process	direct	stable	Resident memory used by the process
`observability.process.memory.virtual`	`process_memory_virtual_bytes`	Metric	bytes	Process	direct	stable	Virtual memory allocated by the process
`observability.process.start_time`	`process_runtime_start_time`	Metric	unix timestamp	Process	direct	stable	Process start time
`observability.process.thread.count`	`process_thread_count`	Metric	integer	Process	direct	stable	Number of active process threads
`observability.process.file_descriptor.count`	`process_open_file_descriptor_count`	Metric	integer	Process	direct	stable	Number of open file descriptors

Python Runtime Mappings¶

Canonical ID	OTel / Prometheus Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.python.gc.collections`	`cpython_gc_collections_total`	Metric	integer	Python Runtime	direct	stable	Number of garbage collection cycles
`observability.python.gc.collected_objects`	`cpython_gc_collected_objects_total`	Metric	integer	Python Runtime	direct	stable	Number of objects reclaimed by garbage collection
`observability.python.gc.uncollectable_objects`	`cpython_gc_uncollectable_objects_total`	Metric	integer	Python Runtime	direct	stable	Number of objects that could not be reclaimed

System Mappings¶

Canonical ID	OTel / Prometheus Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.system.memory.utilization`	`system_memory_utilization_ratio`	Metric	ratio	System	direct	stable	Percentage of system memory currently utilized
`observability.system.network.io`	`system_network_io_bytes_total`	Metric	bytes	System	direct	stable	Network bytes transmitted or received
`observability.system.disk.io`	`system_disk_io_bytes_total`	Metric	bytes	System	direct	stable	Disk bytes read or written
`observability.system.io.direction`	`direction`	Metric Label	string	System I/O	direct	stable	Direction of network or disk I/O

Logging Mappings¶

Canonical ID	OTel Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.log.severity`	`severity`	Log Field	string	Log Record	direct	stable	Severity of the log record
`observability.trace.id`	`trace_id`	Log Field	string	Log Record	direct	stable	Trace associated with the log record
`observability.span.id`	`span_id`	Log Field	string	Log Record	direct	stable	Span associated with the log record

Tracing Mappings¶

Canonical ID	OTel Field	Field Type	Value Type	Scope	Mapping Type	Status	Description
`observability.trace.id`	`trace_id`	Trace Field	string	Trace	direct	stable	Unique identifier for a distributed trace
`observability.trace.span.id`	`span_id`	Span Field	string	Span	direct	stable	Unique identifier for a span
`observability.trace.span.name`	`span.name`	Span Attribute	string	Span	direct	stable	Name of the span operation
`observability.trace.span.duration`	`duration`	Span Field	numeric	Span	direct	stable	Duration of the span
`observability.trace.span.status`	`status`	Span Field	enum	Span	direct	stable	Status of the span

Implementation Derived Fields¶

Some fields appearing in the current Prometheus implementation are derived or exporter specific rather than primary OTel semantic fields.

These should not automatically become independent canonical concepts.

Implementation Field	Representation	Canonical Interpretation	Status
`exported_job`	Prometheus label	Service identity derived from the telemetry pipeline	implementation-specific
`exported_environment`	Prometheus label	Deployment environment derived from resource metadata	implementation-specific
`instance`	Prometheus label	Service or exporter instance identity	implementation-specific

The canonical concepts are therefore:

exported_job
    → observability.service.name

exported_environment
    → observability.environment

These mappings allow the dashboard implementation to use Prometheus labels without making those labels part of the conceptual observability model.

Mapping Types¶

The following mapping types are currently supported:

Mapping Type	Meaning
`direct`	Source field directly represents the canonical concept
`derived`	Canonical value is calculated from one or more source fields
`normalized`	Source field is transformed into a canonical representation
`implementation-specific`	Field exists for a particular exporter or storage system and is not itself a canonical concept

The current inventory is predominantly composed of direct mappings.

Mapping Status¶

Status	Meaning
`stable`	Field and semantic meaning are sufficiently established for dashboard use
`provisional`	Field is currently used but its semantic contract may change
`deprecated`	Field should no longer be used for new implementations
`future`	Concept is planned but not currently implemented

Relationship to Other Observability Documents¶

The observability documentation forms the following dependency chain:

Dashboard Specifications
        ↓
PromQL / LogQL References
        ↓
Metrics Catalogue
        ↓
OTel Fields and Attributes
        ↓
Field Matrix
        ↓
Canonical Mappings
        ↓
Minimum Observability Ontology

The canonical mappings therefore form the boundary between the implementation model and the semantic model.

The next layer, the Minimum Observability Ontology, should consume these canonical identifiers rather than individual Prometheus metric names or instrumentation specific field names.