Add ObservedTimestamp to the Log Data Model (open-telemetry#2184)

* Add ObservedTimestamp to the Log Data Model Resolves open-telemetry#1875 See the issue for the discussion and the description of the source vs observed timestamps. * Fixed based on PR comments Co-authored-by: Joshua MacDonald <[email protected]>
carlosalberto · Dec 10, 2021 · 63566a1 · 63566a1
1 parent f8f9e33
commit 63566a1
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -32,6 +32,8 @@ release.
 
 - Add OTEL_LOGS_EXPORTER environment variable.
   ([#2196](https://github.com/open-telemetry/opentelemetry-specification/pull/2196))
+- Added ObservedTimestamp to the Log Data Model.
+  ([#2184](https://github.com/open-telemetry/opentelemetry-specification/pull/2184))
 
 ### Resource
 

diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md
@@ -178,6 +178,7 @@ Here is the list of fields in a log record:
 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.
@@ -197,6 +198,24 @@ Type: Timestamp, uint64 nanoseconds since Unix epoch.
 Description: Time when the event occurred measured by the origin clock. This
 field is optional, it may be missing if the timestamp is unknown.
 
+### Field: `ObservedTimestamp`
+
+Type: Timestamp, uint64 nanoseconds since Unix epoch.
+
+Description: Time when the event was observed by the collection system. For
+events that originate in OpenTelemetry (e.g. using OpenTelemetry Logging SDK)
+this timestamp is typically set at the generation time and is equal to
+Timestamp. For events originating externally and collected by OpenTelemetry
+(e.g. using Collector) this is the time when OpenTelemetry's code observed the
+event measured by the clock of the OpenTelemetry code. This field SHOULD be set
+once the event is observed by OpenTelemetry.
+
+For converting OpenTelemetry log data to formats that support only one timestamp
+or when receiving OpenTelemetry log data by recipients that support only one
+timestamp internally the following logic is recommended:
+
+- Use `Timestamp` if it is present, otherwise use `ObservedTimestamp`.
+
 ### Trace Context Fields
 
 #### Field: `TraceId`