Logs API - initialize LogRecordData.Timestamp with MinValue

src/OpenTelemetry.Api/CHANGELOG.md

@@ -10,6 +10,14 @@ Notes](../../RELEASENOTES.md).
   Add support for using environment variables as context propagation carriers.
   ([#7174](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7174))
 
+* **Breaking change** (pre-release only versions): The default value of
+  the `Timestamp` property on `LogRecordData` has changed from `DateTime.UtcNow`
+  to `DateTime.MinValue`. `DateTime.MinValue` represents an unset timestamp as
+  defined by the OpenTelemetry specification. Callers of the [Logs API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/api.md)
+  who relied on the timestamp being populated automatically must now set
+  `Timestamp = DateTime.UtcNow` explicitly on their `LogRecordData` instance.
+  ([#7045](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7045))
+
 ## 1.15.3
 
 Released 2026-Apr-21

src/OpenTelemetry.Api/Logs/LogRecordData.cs

@@ -26,7 +26,7 @@ namespace OpenTelemetry.Logs;
     struct LogRecordData
 #pragma warning restore CA1815 // Override equals and operator equals on value types
 {
-    internal DateTime TimestampBacking = DateTime.UtcNow;
+    internal DateTime TimestampBacking = DateTime.MinValue;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="LogRecordData"/> struct.
@@ -35,7 +35,7 @@ struct LogRecordData
     /// Notes:
     /// <list type="bullet">
     /// <item>The <see cref="Timestamp"/> property is initialized to <see
-    /// cref="DateTime.UtcNow"/> automatically.</item>
+    /// cref="DateTime.MinValue"/> automatically.</item>
     /// <item>The <see cref="TraceId"/>, <see cref="SpanId"/>, and <see
     /// cref="TraceFlags"/> properties will be set using the <see
     /// cref="Activity.Current"/> instance.</item>
@@ -51,7 +51,9 @@ public LogRecordData()
     /// </summary>
     /// <remarks>
     /// Note: The <see cref="Timestamp"/> property is initialized to <see
-    /// cref="DateTime.UtcNow"/> automatically.
+    /// cref="DateTime.MinValue"/> automatically, indicating the timestamp is
+    /// not set. Set <see cref="Timestamp"/> explicitly to provide the time the
+    /// event occurred.
     /// </remarks>
     /// <param name="activity">Optional <see cref="Activity"/> used to populate
     /// trace context properties (<see cref="TraceId"/>, <see cref="SpanId"/>,
@@ -66,7 +68,9 @@ public LogRecordData(Activity? activity)
     /// </summary>
     /// <remarks>
     /// Note: The <see cref="Timestamp"/> property is initialized to <see
-    /// cref="DateTime.UtcNow"/> automatically.
+    /// cref="DateTime.MinValue"/> automatically, indicating the timestamp is
+    /// not set. Set <see cref="Timestamp"/> explicitly to provide the time the
+    /// event occurred.
     /// </remarks>
     /// <param name="activityContext"><see cref="ActivityContext"/> used to
     /// populate trace context properties (<see cref="TraceId"/>, <see
@@ -82,9 +86,16 @@ public LogRecordData(in ActivityContext activityContext)
     /// Gets or sets the log timestamp.
     /// </summary>
     /// <remarks>
-    /// Note: If <see cref="Timestamp"/> is set to a value with <see
-    /// cref="DateTimeKind.Local"/> it will be automatically converted to
-    /// UTC using <see cref="DateTime.ToUniversalTime"/>.
+    /// Notes:
+    /// <list type="bullet">
+    /// <item>The default value is <see cref="DateTime.MinValue"/>, which is
+    /// treated as "not set" per the OpenTelemetry specification. When
+    /// exported via OTLP this maps to <c>time_unix_nano = 0</c> (unknown or
+    /// missing timestamp).</item>
+    /// <item>If <see cref="Timestamp"/> is set to a value with <see
+    /// cref="DateTimeKind.Local"/> it will be automatically converted to UTC
+    /// using <see cref="DateTime.ToUniversalTime"/>.</item>
+    /// </list>
     /// </remarks>
     public DateTime Timestamp
     {

src/OpenTelemetry.Exporter.Console/ConsoleLogRecordExporter.cs

@@ -1,6 +1,7 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+using System.Globalization;
 using OpenTelemetry.Internal;
 using OpenTelemetry.Logs;
 using OpenTelemetry.Resources;
@@ -47,7 +48,8 @@ public override ExportResult Export(in Batch<LogRecord> batch)
 
         foreach (var logRecord in batch)
         {
-            this.WriteLine($"{"LogRecord.Timestamp:",-RightPaddingLength}{logRecord.Timestamp:yyyy-MM-ddTHH:mm:ss.fffffffZ}");
+            var timestamp = logRecord.Timestamp;
+            this.WriteLine($"{"LogRecord.Timestamp:",-RightPaddingLength}{(timestamp == DateTime.MinValue ? "(not set)" : timestamp.ToString("yyyy-MM-ddTHH:mm:ss.fffffffZ", CultureInfo.InvariantCulture))}");
 
             if (logRecord.TraceId != default)
             {

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/Serializer/ProtobufOtlpLogSerializer.cs

@@ -179,9 +179,25 @@ internal static int WriteLogRecord(byte[] buffer, int writePosition, SdkLimitOpt
         var logRecordLengthPosition = otlpTagWriterState.WritePosition;
         otlpTagWriterState.WritePosition += ReserveSizeForLength;
 
-        var timestamp = (ulong)logRecord.Timestamp.ToUnixTimeNanoseconds();
-        otlpTagWriterState.WritePosition = ProtobufSerializer.WriteFixed64WithTag(otlpTagWriterState.Buffer, otlpTagWriterState.WritePosition, ProtobufOtlpLogFieldNumberConstants.LogRecord_Time_Unix_Nano, timestamp);
-        otlpTagWriterState.WritePosition = ProtobufSerializer.WriteFixed64WithTag(otlpTagWriterState.Buffer, otlpTagWriterState.WritePosition, ProtobufOtlpLogFieldNumberConstants.LogRecord_Observed_Time_Unix_Nano, timestamp);
+        var logTimestamp = logRecord.Timestamp;
+        ulong timeUnixNano;
+        ulong observedTimeUnixNano;
+        if (logTimestamp != DateTime.MinValue)
+        {
+            // Timestamp was explicitly set: use it for both fields.
+            timeUnixNano = (ulong)logTimestamp.ToUnixTimeNanoseconds();
+            observedTimeUnixNano = timeUnixNano;
+        }
+        else
+        {
+            // Timestamp not set -> time_unix_nano = 0 ("unknown or missing" per OTLP spec).
+            // observed_time_unix_nano MUST still be populated (proto spec requirement).
+            timeUnixNano = 0;
+            observedTimeUnixNano = (ulong)DateTime.UtcNow.ToUnixTimeNanoseconds();
+        }
+
+        otlpTagWriterState.WritePosition = ProtobufSerializer.WriteFixed64WithTag(otlpTagWriterState.Buffer, otlpTagWriterState.WritePosition, ProtobufOtlpLogFieldNumberConstants.LogRecord_Time_Unix_Nano, timeUnixNano);
+        otlpTagWriterState.WritePosition = ProtobufSerializer.WriteFixed64WithTag(otlpTagWriterState.Buffer, otlpTagWriterState.WritePosition, ProtobufOtlpLogFieldNumberConstants.LogRecord_Observed_Time_Unix_Nano, observedTimeUnixNano);
 
         otlpTagWriterState.WritePosition = ProtobufSerializer.WriteEnumWithTag(otlpTagWriterState.Buffer, otlpTagWriterState.WritePosition, ProtobufOtlpLogFieldNumberConstants.LogRecord_Severity_Number, logRecord.Severity.HasValue ? (int)logRecord.Severity : 0);
 

src/OpenTelemetry/Logs/LogRecord.cs

@@ -104,9 +104,14 @@ internal enum LogRecordSource
     /// Gets or sets the log timestamp.
     /// </summary>
     /// <remarks>
-    /// Note: If <see cref="Timestamp"/> is set to a value with <see
-    /// cref="DateTimeKind.Local"/> it will be automatically converted to
-    /// UTC using <see cref="DateTime.ToUniversalTime"/>.
+    /// Notes:
+    /// <list type="bullet">
+    /// <item>The default value is <see cref="DateTime.MinValue"/>, which is
+    /// treated as "not set" per the OpenTelemetry specification.</item>
+    /// <item>If <see cref="Timestamp"/> is set to a value with <see
+    /// cref="DateTimeKind.Local"/> it will be automatically converted to UTC
+    /// using <see cref="DateTime.ToUniversalTime"/>.</item>
+    /// </list>
     /// </remarks>
     public DateTime Timestamp
     {

test/OpenTelemetry.Api.Tests/Logs/LogRecordDataTests.cs

@@ -86,10 +86,8 @@ public void ActivityContextConstructorTest()
     [Fact]
     public void TimestampTest()
     {
-        var nowUtc = DateTime.UtcNow;
-
         var record = new LogRecordData();
-        Assert.True(record.Timestamp >= nowUtc);
+        Assert.Equal(DateTime.MinValue, record.Timestamp);
 
         record = default;
         Assert.Equal(DateTime.MinValue, record.Timestamp);

test/OpenTelemetry.Exporter.OpenTelemetryProtocol.Tests/OtlpLogExporterTests.cs

@@ -429,6 +429,43 @@ public void CheckToOtlpLogRecordTimestamps()
         Assert.True(otlpLogRecord.ObservedTimeUnixNano > 0);
     }
 
+    [Fact]
+    public void CheckToOtlpLogRecordTimestamps_BridgeApi_UnsetTimestamp()
+    {
+        // When the Bridge API caller leaves Timestamp as DateTime.MinValue
+        // (not set), the serializer must write:
+        //   time_unix_nano         = 0   (unknown/missing per OTLP spec)
+        //   observed_time_unix_nano >= the time of observation (MUST be set per OTLP spec)
+        var logRecords = new List<LogRecord>();
+        using var loggerProvider = Sdk.CreateLoggerProviderBuilder()
+            .AddInMemoryExporter(logRecords)
+            .Build();
+
+        var bridgeLogger = loggerProvider.GetLogger("OtlpLogExporterTests");
+
+        // Capture a lower-bound for the observation timestamp before emitting.
+        var beforeEmitUtc = DateTime.UtcNow;
+
+        // Emit with default LogRecordData -- Timestamp stays DateTime.MinValue.
+        bridgeLogger.EmitLog(new LogRecordData());
+
+        Assert.Single(logRecords);
+        Assert.Equal(DateTime.MinValue, logRecords[0].Timestamp);
+
+        var otlpLogRecord = ToOtlpLogs(DefaultSdkLimitOptions, new ExperimentalOptions(), logRecords[0]);
+
+        Assert.NotNull(otlpLogRecord);
+
+        // time_unix_nano must be 0 -- "unknown or missing" per OTLP spec.
+        Assert.Equal(0UL, otlpLogRecord.TimeUnixNano);
+
+        // observed_time_unix_nano must be >= the moment we captured before emitting.
+        var beforeEmitNano = (ulong)new DateTimeOffset(beforeEmitUtc).ToUnixTimeNanoseconds();
+        Assert.True(
+            otlpLogRecord.ObservedTimeUnixNano >= beforeEmitNano,
+            $"ObservedTimeUnixNano ({otlpLogRecord.ObservedTimeUnixNano}) should be >= beforeEmitNano ({beforeEmitNano})");
+    }
+
     [Fact]
     public void CheckToOtlpLogRecordTraceIdSpanIdFlagWithNoActivity()
     {