Restructure log data model to be more like metrics

thompson-tomo · thompson-tomo · commit 35cfdb06c0c2 · 2025-12-17T19:37:43.000+11:00
diff --git a/specification/logs/README.md b/specification/logs/README.md
@@ -196,7 +196,7 @@ Logs can be correlated with the rest of observability data in a few dimensions:
 - By the **origin of the telemetry**, also known as the Resource context.
   OpenTelemetry traces and metrics contain information about the Resource they
   come from. We extend this practice to logs by including the
-  [Resource](data-model.md#field-resource) in LogRecords.
+  [Resource](../resource/README.md) in Log data streams.
 
 These 3 correlations can be the foundation of powerful navigational, filtering,
 querying and analytical capabilities. OpenTelemetry aims to record and collects
diff --git a/specification/logs/api.md b/specification/logs/api.md
@@ -67,10 +67,10 @@ The `LoggerProvider` MUST provide the following functions:
 
 #### Get a Logger
 
-This API MUST accept the following [instrumentation scope](data-model.md#field-instrumentationscope)
+This API MUST accept the following [instrumentation scope](../common/instrumentation-scope.md)
 parameters:
 
-* `name`: Specifies the name of the [instrumentation scope](../common/instrumentation-scope.md),
+* `name`: Specifies the name of the instrumentation scope,
   such as the [instrumentation library](../glossary.md#instrumentation-library)
   (e.g. `io.opentelemetry.contrib.mongodb`), package, module or class name.
   If an application or library has built-in OpenTelemetry instrumentation, both
diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md
@@ -12,32 +12,36 @@ weight: 2
 
 <!-- toc -->
 
+- [Overview](#overview)
 - [Design Notes](#design-notes)
   * [Requirements](#requirements)
-  * [Events](#events)
   * [Definitions Used in this Document](#definitions-used-in-this-document)
     + [Type `any`](#type-any)
     + [Type `map`](#type-mapstring-any)
   * [Field Kinds](#field-kinds)
-- [Log and Event Record Definition](#log-and-event-record-definition)
-  * [Field: `Timestamp`](#field-timestamp)
-  * [Field: `ObservedTimestamp`](#field-observedtimestamp)
-  * [Trace Context Fields](#trace-context-fields)
+- [Model Details](#model-details)
+  * [Open Telemetry Protocol data model](#open-telemetry-protocol-data-model)
+    + [Field: `Timestamp`](#field-timestamp)
+    + [Field: `ObservedTimestamp`](#field-observedtimestamp)
     + [Field: `TraceId`](#field-traceid)
     + [Field: `SpanId`](#field-spanid)
     + [Field: `TraceFlags`](#field-traceflags)
-  * [Severity Fields](#severity-fields)
     + [Field: `SeverityText`](#field-severitytext)
     + [Field: `SeverityNumber`](#field-severitynumber)
-    + [Mapping of `SeverityNumber`](#mapping-of-severitynumber)
-    + [Reverse Mapping](#reverse-mapping)
-    + [Error Semantics](#error-semantics)
-    + [Displaying Severity](#displaying-severity)
-    + [Comparing Severity](#comparing-severity)
-  * [Field: `Body`](#field-body)
-  * [Field: `Attributes`](#field-attributes)
-    + [Errors and Exceptions](#errors-and-exceptions)
-  * [Field: `EventName`](#field-eventname)
+    + [Field: `Body`](#field-body)
+    + [Field: `Attributes`](#field-attributes)
+      - [Errors and Exceptions](#errors-and-exceptions)
+    + [Field: `EventName`](#field-eventname)
+- [Log Records](#log-records)
+  * [Logs](#logs)
+  * [Events](#events)
+- [Severity](#severity)
+  * [Mapping of `Severity`](#mapping-of-severity)
+    + [Mapping to `SeverityNumber`](#mapping-to-severitynumber)
+    + [Mapping from `SeverityNumber`](#mapping-from-severitynumber)
+  * [Error Semantics](#error-semantics)
+  * [Displaying Severity](#displaying-severity)
+  * [Comparing Severity](#comparing-severity)
 - [Example Log Records](#example-log-records)
 - [Example Mappings](#example-mappings)
 - [References](#references)
@@ -46,6 +50,8 @@ weight: 2
 
 </details>
 
+## Overview
+
 This is a data model and semantic conventions that allow to represent logs from
 various sources: application log files, machine generated events, system logs,
 etc. Existing log formats can be unambiguously mapped to this data model.
@@ -102,14 +108,6 @@ The Data Model aims to successfully represent 3 sorts of logs and events:
   we include in the logs. We can likely modify the source code of the
   application if needed.
 
-### Events
-
-Events are OpenTelemetry's standardized format for LogRecords. All semantic
-conventions defined for logs SHOULD be formatted as Events. Requirements and details for the Event format can be found in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md).
-
-Events are intended to be used by OpenTelemetry instrumentation. It is not a
-requirement that all LogRecords are formatted as Events.
-
 ### Definitions Used in this Document
 
 In this document we refer to types `any` and `map<string, any>`, defined as
@@ -189,38 +187,48 @@ decision about when to use a top-level named field:
 Both of the above conditions were required to give the field a place in the
 top-level structure of the record.
 
-## Log and Event Record Definition
+## Model Details
+
+### Open Telemetry Protocol data model
+
+The OpenTelemetry protocol (OTLP) data model is composed of Log data streams. These streams are in turn composed of log records.
 
-[Appendix A](./data-model-appendix.md#appendix-a-example-mappings) contains many examples that show how
-existing log formats map to the fields defined below. If there are questions
-about the meaning of the field reviewing the examples may be helpful.
+Log streams are grouped into individual Log objects, identified by:
 
-Here is the list of fields in a log record:
+- The originating Resource attributes
+- The instrumentation Scope (e.g., instrumentation library name, version)
 
-| Field Name | Description |
-| ---------- | ----------- |
-| Timestamp | Time when the event occurred. |
-| ObservedTimestamp | Time when the event was observed. |
-| TraceId | Request trace id. |
-| SpanId | Request span id. |
-| TraceFlags | W3C trace flag. |
-| SeverityText | The severity text (also known as log level). |
-| SeverityNumber | Numerical value of the severity. |
-| Body | The body of the log record. |
-| Attributes | Additional information about the event. |
-| EventName | Name that identifies the class / type of event. |
+The `Log` record is defined by the following properties:
+
+| Field Name | Category | Description |
+| ---------- | -------- | ----------- |
+| Timestamp | | Time when the event occurred. |
+| ObservedTimestamp | | Time when the event was observed. |
+| TraceId | Trace Context | Request trace id. |
+| SpanId | Trace Context | Request span id. |
+| TraceFlags Trace Context | Trace Context | W3C trace flag. |
+| SeverityText | Severity | The severity text (also known as log level). |
+| SeverityNumber | Severity | Numerical value of the severity. |
+| Body | | The body of the log record. |
+| Attributes | | Additional information about the event. |
+| EventName | | Name that identifies the class / type of event. |
+
+> [!NOTE]
+> [Appendix A](./data-model-appendix.md#appendix-a-example-mappings) contains many examples that show how
+> existing log formats map to the fields defined above. If there are questions
+> about the meaning of the field reviewing the examples may be helpful.
 
 Below is the detailed description of each field.
 
-### Field: `Timestamp`
+#### Field: `Timestamp`
 
 Type: Timestamp, uint64 nanoseconds since Unix epoch.
 
 Description: Time when the event occurred measured by the origin clock, i.e. the
 time at the source. This field is optional, it may be missing if the source
 timestamp is unknown.
 
-### Field: `ObservedTimestamp`
+#### Field: `ObservedTimestamp`
 
 Type: Timestamp, uint64 nanoseconds since Unix epoch.
 
@@ -238,8 +246,6 @@ timestamp internally the following logic is recommended:
 
 - Use `Timestamp` if it is present, otherwise use `ObservedTimestamp`.
 
-### Trace Context Fields
-
 #### Field: `TraceId`
 
 Type: byte sequence.
@@ -266,8 +272,6 @@ Description: Trace flag as defined in
 specification. At the time of writing the specification defines one flag - the
 SAMPLED flag. This field is optional.
 
-### Severity Fields
-
 #### Field: `SeverityText`
 
 Type: string.
@@ -305,7 +309,77 @@ The following table defines the meaning of `SeverityNumber` value:
 
 `SeverityNumber=0` MAY be used to represent an unspecified value.
 
-#### Mapping of `SeverityNumber`
+#### Field: `Body`
+
+Type: [`any`](#type-any) or [AnyValue](../common/README.md#anyvalue).
+
+Description: A value containing the body of the log record. Can be for example
+a human-readable string message (including multi-line) describing the event in
+a free form or it can be a structured data composed of arrays and maps of other
+values. Body MUST support [AnyValue](../common/README.md#anyvalue)
+to preserve the semantics of structured logs emitted by the applications.
+Can vary for each occurrence of the event coming from the same source.
+This field is optional.
+
+#### Field: `Attributes`
+
+Type: [`map<string, any>`](#type-mapstring-any) or [Attribute Collection](../common/README.md#attribute-collections).
+
+Description: Additional information about the specific event occurrence. Unlike
+the [`Resource`](../resource/sdk.md), which is fixed for a particular source, `Attributes` can
+vary for each occurrence of the event coming from the same source. Can contain
+information about the request context.
+This field is optional.
+
+##### Errors and Exceptions
+
+Additional information about errors and/or exceptions that are associated with
+a log record MAY be included in the structured data in the `Attributes` section
+of the record.
+If included, they MUST follow the OpenTelemetry
+[semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md).
+
+#### Field: `EventName`
+
+Type: string.
+
+Description: Name that identifies the class / type of the [Event](#events).
+This name SHOULD uniquely identify the event structure (both attributes and body).
+A log record with a non-empty event name is an [Event](#events).
+
+## Log Records
+
+It is not a requirement that all LogRecords are formatted as Events hence the 2 formats described below.
+
+> [!NOTE]
+> Events are intended to be used by OpenTelemetry instrumentation.
+
+### Logs
+
+The requirements of logs are:
+
+- A log MUST NOT have an event name.
+- Attributes SHOULD be used to represent details and provide additional context about the event.
+- Body may be used.
+- Events SHOULD specify a severity number.
+
+Logs are not defined in semantic conventions.
+
+### Events
+
+Events are OpenTelemetry's standardized format for LogRecords. The requirements of events are:
+
+- An event MUST have an event name that uniquely identifies the event structure.
+- Attributes SHOULD be used to represent details and provide additional context about the event.
+- Events SHOULD specify a severity number.
+
+All semantic conventions defined for logs SHOULD be formatted as Events with the requirements and details for the Event format can be found in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md).
+
+## Severity
+
+### Mapping of `Severity`
+
+#### Mapping to `SeverityNumber`
 
 Mappings from existing logging systems and formats (or **source format** for
 short) must define how severity (or log level) of that particular format
@@ -336,7 +410,7 @@ records with missing severity information distinctly or may interpret log
 records with missing `SeverityNumber` and `SeverityText` fields as if the
 `SeverityNumber` was set equal to INFO (numeric value of 9).
 
-#### Reverse Mapping
+#### Mapping from `SeverityNumber`
 
 When performing a reverse mapping from `SeverityNumber` to a specific format
 and the `SeverityNumber` has no corresponding mapping entry for that format
@@ -347,7 +421,7 @@ For example Zap has only one severity in the INFO range, called "Info". When
 doing reverse mapping all `SeverityNumber` values in INFO range (numeric 9-12)
 will be mapped to Zap’s "Info" level.
 
-#### Error Semantics
+### Error Semantics
 
 If `SeverityNumber` is present and has a value of ERROR (numeric 17) or higher
 then it is an indication that the log record represents an erroneous situation.
@@ -364,7 +438,7 @@ recommended value in this case is INFO (numeric 9). See
 [Appendix B](./data-model-appendix.md#appendix-b-severitynumber-example-mappings) for more mapping
 examples.
 
-#### Displaying Severity
+### Displaying Severity
 
 The following table defines the recommended short name for each
 `SeverityNumber` value. The short name can be used for example for representing
@@ -417,51 +491,13 @@ dropdown list, which lists all distinct `SeverityText` values that are known to
 the system (which can be a large number of elements, often differing only in
 capitalization or abbreviated, e.g. "Info" vs "Information").
 
-#### Comparing Severity
+### Comparing Severity
 
 In the contexts where severity participates in less-than / greater-than
 comparisons `SeverityNumber` field should be used.
 Special handling MAY be given to `SeverityNumber=0`
 when it is used to represent an unspecified severity.
 
-### Field: `Body`
-
-Type: [`any`](#type-any) or [AnyValue](../common/README.md#anyvalue).
-
-Description: A value containing the body of the log record. Can be for example
-a human-readable string message (including multi-line) describing the event in
-a free form or it can be a structured data composed of arrays and maps of other
-values. Body MUST support [AnyValue](../common/README.md#anyvalue)
-to preserve the semantics of structured logs emitted by the applications.
-Can vary for each occurrence of the event coming from the same source.
-This field is optional.
-
-### Field: `Attributes`
-
-Type: [`map<string, any>`](#type-mapstring-any) or [Attribute Collection](../common/README.md#attribute-collections).
-
-Description: Additional information about the specific event occurrence. Unlike
-the [`Resource`](../resource/sdk.md), which is fixed for a particular source, `Attributes` can
-vary for each occurrence of the event coming from the same source. Can contain
-information about the request context (other than [Trace Context Fields](#trace-context-fields)).
-This field is optional.
-
-#### Errors and Exceptions
-
-Additional information about errors and/or exceptions that are associated with
-a log record MAY be included in the structured data in the `Attributes` section
-of the record.
-If included, they MUST follow the OpenTelemetry
-[semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md).
-
-### Field: `EventName`
-
-Type: string.
-
-Description: Name that identifies the class / type of the [Event](#events).
-This name SHOULD uniquely identify the event structure (both attributes and body).
-A log record with a non-empty event name is an [Event](#events).
-
 ## Example Log Records
 
 For example log records see
diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md
@@ -266,8 +266,8 @@ In this document we refer to `ReadableLogRecord` and `ReadWriteLogRecord`, defin
 
 A function receiving this as an argument MUST be able to access all the
 information added to the [LogRecord](data-model.md#log-and-event-record-definition). It MUST also be able to
-access the [Instrumentation Scope](./data-model.md#field-instrumentationscope)
-and [Resource](./data-model.md#field-resource) information (implicitly)
+access the [Instrumentation Scope](../common/instrumentation-scope.md)
+and [Resource](../resource/README.md) information (implicitly)
 associated with the `LogRecord`.
 
 The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from
@@ -412,7 +412,7 @@ in order to support filtering via [`Logger.Enabled`](api.md#enabled).
 
 * [Context](../context/README.md) explicitly passed by the caller or the current
   Context
-* [Instrumentation Scope](./data-model.md#field-instrumentationscope) associated
+* [Instrumentation Scope](../common/instrumentation-scope.md) associated
   with the `Logger`
 * [Severity Number](./data-model.md#field-severitynumber) passed by the caller
 * [Event Name](./data-model.md#field-eventname) passed by the caller
