> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Open Telemetry Logs Data Model
> Overview of the OpenTelemetry logs data model that standardizes diverse log formats into a unified schema for consistent indexing, querying, and trace and metric correlation
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.
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.
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:
```yaml theme={null}
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.
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:
```text theme={null}
<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.
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):
```yaml theme={null}
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.
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.
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/](https://opentelemetry.io/)
* OTLP protocol reference: [https://opentelemetry.io/docs/reference/specification/protocol/otlp/](https://opentelemetry.io/docs/reference/specification/protocol/otlp/)
* Protobuf: [https://protobuf.dev/](https://protobuf.dev/)
* Syslog (RFC 5424): [https://datatracker.ietf.org/doc/html/rfc5424](https://datatracker.ietf.org/doc/html/rfc5424)
* Common Log Format (CLF): [https://httpd.apache.org/docs/1.3/logs.html#common](https://httpd.apache.org/docs/1.3/logs.html#common)
* Kubernetes documentation: [https://kubernetes.io/](https://kubernetes.io/)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.