Open Telemetry Logs Data Model

Explore the OpenTelemetry (OTel) logs data model and how it standardizes diverse log formats into a consistent schema suitable for indexing, querying, and correlating with traces and metrics. Logs arrive in many formats: syslog from operating systems and network devices, web server access logs in Common Log Format (CLF), and proprietary application logs. The OTel logs data model provides a unified schema to represent log records from third-party systems (Nginx, Apache), system logs (syslog), and first-party application instrumentation so that downstream tools and platforms can interpret them consistently.

A presentation slide titled "Logs Data Model – Overview" showing a central box labeled "Logs Data Model" with "Unified schema for log records." Below are three numbered log sources: 1) System (Syslog), 2) Third-party (NGINX), and 3) First-party (custom app).

Why a unified logs schema? The logs data model defines what a log record is: a small set of typed core fields plus an extensible attributes map. This shared definition standardizes how timestamps, severity, and message content are captured and transferred, reducing ambiguity and improving interoperability between collectors, exporters, and observability backends.

A presentation slide titled "Why the Logs Data Model Exists" showing four bullet points explaining its purposes: to establish a shared log record definition, define essential data to capture and transfer, ensure consistent storage and processing, and enable uniform interpretation across logging systems and tools. The slide has a rounded info box with orange dot icons and a Copyright KodeKloud mark.

Events in OpenTelemetry logs OpenTelemetry treats some log records as structured “events” using semantic conventions borrowed from span events. An event-style log record exposes predictable fields such as timestamp, severity, body, and resource identifiers. When you emit logs as events from new instrumentation, you gain consistent indexing, improved filtering, and stronger trace-log correlation. Example of an event-style log record:

timestamp: 2025-08-03T13:45:12Z
severity: ERROR
body: "User login failed"
user.id: 12345
service.name: "auth-service"

Design guidance:

Prefer emitting structured, event-style logs for new instrumentation.
Legacy logs can remain unmodified, but structured events provide better machine-readability and enable richer analysis.

A presentation slide titled "Understanding Events in OTel Logs" showing an "Events" box listing fields (Timestamp, Severity, Body, Resource identifiers) on the left and numbered points on the right (Structured LogRecords, Predefined fields, Consistency, Optional for legacy).

Logical structure of an OTel log record An OTel log record combines:

A compact set of typed, named fields (for consistent querying and correlation).
A flexible attributes map and resource attributes for environment-specific key-value context.

Core named fields (common and typed):

Field	Purpose
`timestamp`	Source event time (time_unix_nano — nanoseconds since Unix epoch).
`observed_timestamp`	When the Collector observed the log (observed_time_unix_nano).
`severity_text` / `severity_number`	Human-readable and numeric severity values.
`body`	Human-readable message or payload.
`trace_id`, `span_id`, `trace_flags`	Optional trace correlation fields for linking logs to traces.

Mapped fields:

attributes and resource attributes: arbitrary key/value pairs (host, pod name, container ID, process ID, etc.). These provide context but are less strictly typed and may vary across sources.

A syslog example mapped into the OTel schema:

<34>1 2021-07-02T18:00:00Z host app 1234 - - Disk error on /dev/sda1

Record {
    Timestamp: 1625247600000000000  # time_unix_nano (2021-07-02T18:00:00Z)
    Body: "Disk error on /dev/sda1"
    Resource: { service.name: "app" }
    Attributes: { host: "host", processID: "1234" }
    SeverityNumber: 17    # maps syslog severity 2 (Critical) to OTel ERROR range (17–20)
}

Key recommendation: be deliberate when naming attribute keys to reduce ambiguity and improve queryability across heterogeneous log sources.

A slide titled "Logical Structure of a Log and Event Record" showing a two-column table of log field names (Timestamp, ObservedTimestamp, TraceId, SpanId, TraceFlags, SeverityText, etc.) and short descriptions for each. The image appears to be a KodeKloud copyright slide.

Timestamps and severity numbers OpenTelemetry represents timestamps as 64-bit unsigned integers (nanoseconds since the Unix epoch) and captures both the original event time and when the Collector observed it. Example timestamps (nanoseconds since epoch):

Timestamp: 1625247600000000000  # time_unix_nano, 2021-07-02T18:00:00Z
ObservedTimestamp: 1625247601000000000  # observed_time_unix_nano (+1 second)

Severity is represented as both text and a numeric severity number. Numeric ranges map to categories as follows:

Severity Category	Numeric Range	Typical meaning
TRACE	1–4	Very fine-grained diagnostic events.
DEBUG	5–8	Debugging-level events useful to developers.
INFO	9–12	Routine informational events.
WARN	13–16	Potential issues or warnings.
ERROR	17–20	Errors that indicate failures in operations.
FATAL	21–24	Severe failures, usually requiring immediate attention.

When exporting to systems that don’t support the exact numeric level, OTel exporters typically select the nearest supported severity.

A color-coded "SeverityNumber Mapping Table" showing severity ranges (1–24) mapped to categories like TRACE, DEBUG, INFO, WARN, ERROR, and FATAL with short meanings for each. The table explains what each level signifies (e.g., debugging events, warnings, errors, fatal crashes).

Mapping, exporters, and efficiency The logs data model is designed to map raw logs into OTel’s schema and then export them in target formats (OTLP, JSON, etc.) with minimal semantic loss. When a direct mapping is impossible (e.g., non-matching severity models), select the nearest compatible value. Best practices for efficient transport and processing:

Use Protobuf encoding for OTLP for compact, performant transport.
Batch shared metadata (resource attributes and instrumentation scope) so identical metadata is sent once per batch instead of repeated for each log record. This is especially important for high-throughput environments like Kubernetes pods.
Prefer structured event-style logs to make downstream indexing, filtering, and correlation more efficient.

A presentation slide titled "Mapping, Reverse Mapping, and Efficiency" showing a flowchart from Raw Logs → OTel Schema → Exporter Formats (JSON/OTLP/others). Colored callout boxes list optimizations like "Severity mismatch" (map to nearest severity number), "Protobuf" (encoding for OTLP), and "Batch resource & Scope metadata" (reduce overhead).

When designing instrumentation, prefer structured event-style logs (with timestamp, severity, body, and resource identifiers). This improves filtering, correlation with traces, and consistency across diverse log sources.

Links and references

OpenTelemetry: https://opentelemetry.io/
OTLP protocol reference: https://opentelemetry.io/docs/reference/specification/protocol/otlp/
Protobuf: https://protobuf.dev/
Syslog (RFC 5424): https://datatracker.ietf.org/doc/html/rfc5424
Common Log Format (CLF): https://httpd.apache.org/docs/1.3/logs.html#common
Kubernetes documentation: https://kubernetes.io/

Course Introduction

Observability Core Concepts

OpenTelemetry Core Concepts

Span Anatomy and Context Propagation

Instrumentation

Metrics Data Model

Recording Measurements

Logs

OTel Collector Foundations

OTel Collector Core Components

Transforming Telemetry – Pipeline Processing

OpenTelemetry in Kubernetes

OpenTelemetry Collector: Debugging, Operations, and Scaling

Extended Topics

Open Telemetry Logs Data Model

Watch Video