Add ObservedTimestamp to LogRecordData

Author: juliuskoval

src/OpenTelemetry.Api/.publicApi/Experimental/PublicAPI.Unshipped.txt

@@ -73,3 +73,5 @@
 [OTEL1001]static OpenTelemetry.Logs.LogRecordAttributeList.CreateFromEnumerable(System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string!, object?>>! attributes) -> OpenTelemetry.Logs.LogRecordAttributeList
 [OTEL1001]static OpenTelemetry.Logs.LogRecordSeverityExtensions.ToShortName(this OpenTelemetry.Logs.LogRecordSeverity logRecordSeverity) -> string!
 [OTEL1001]virtual OpenTelemetry.Logs.LoggerProvider.TryCreateLogger(string? name, out OpenTelemetry.Logs.Logger? logger) -> bool
+[OTEL1001]OpenTelemetry.Logs.LogRecordData.ObservedTimestamp.get -> System.DateTime
+[OTEL1001]OpenTelemetry.Logs.LogRecordData.ObservedTimestamp.set -> void

src/OpenTelemetry.Api/Logs/LogRecordData.cs

@@ -28,13 +28,15 @@ struct LogRecordData
 {
     internal DateTime TimestampBacking = DateTime.UtcNow;
 
+    internal DateTime ObservedTimestampBacking = DateTime.UtcNow;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="LogRecordData"/> struct.
     /// </summary>
     /// <remarks>
     /// Notes:
     /// <list type="bullet">
-    /// <item>The <see cref="Timestamp"/> property is initialized to <see
+    /// <item>The <see cref="Timestamp"/> and <see cref="ObservedTimestamp"/> properties are initialized to <see
     /// cref="DateTime.UtcNow"/> automatically.</item>
     /// <item>The <see cref="TraceId"/>, <see cref="SpanId"/>, and <see
     /// cref="TraceFlags"/> properties will be set using the <see
@@ -50,7 +52,7 @@ public LogRecordData()
     /// Initializes a new instance of the <see cref="LogRecordData"/> struct.
     /// </summary>
     /// <remarks>
-    /// Note: The <see cref="Timestamp"/> property is initialized to <see
+    /// Note: <see cref="Timestamp"/> and <see cref="ObservedTimestamp"/> properties are initialized to <see
     /// cref="DateTime.UtcNow"/> automatically.
     /// </remarks>
     /// <param name="activity">Optional <see cref="Activity"/> used to populate
@@ -65,7 +67,7 @@ public LogRecordData(Activity? activity)
     /// Initializes a new instance of the <see cref="LogRecordData"/> struct.
     /// </summary>
     /// <remarks>
-    /// Note: The <see cref="Timestamp"/> property is initialized to <see
+    /// Note: <see cref="Timestamp"/> and <see cref="ObservedTimestamp"/> properties are initialized to <see
     /// cref="DateTime.UtcNow"/> automatically.
     /// </remarks>
     /// <param name="activityContext"><see cref="ActivityContext"/> used to
@@ -92,6 +94,20 @@ public DateTime Timestamp
         set => this.TimestampBacking = value.Kind == DateTimeKind.Local ? value.ToUniversalTime() : value;
     }
 
+    /// <summary>
+    /// Gets or sets the timestamp when the log was recorded by OpenTelemetry's code.
+    /// </summary>
+    /// <remarks>
+    /// Note: If <see cref="ObservedTimestamp"/> is set to a value with <see
+    /// cref="DateTimeKind.Local"/> it will be automatically converted to
+    /// UTC using <see cref="DateTime.ToUniversalTime"/>.
+    /// </remarks>
+    public DateTime ObservedTimestamp
+    {
+        readonly get => this.ObservedTimestampBacking;
+        set { this.ObservedTimestampBacking = value.Kind == DateTimeKind.Local ? value.ToUniversalTime() : value; }
+    }
+
     /// <summary>
     /// Gets or sets the log <see cref="ActivityTraceId"/>.
     /// </summary>

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

@@ -180,8 +180,10 @@ internal static int WriteLogRecord(byte[] buffer, int writePosition, SdkLimitOpt
         otlpTagWriterState.WritePosition += ReserveSizeForLength;
 
         var timestamp = (ulong)logRecord.Timestamp.ToUnixTimeNanoseconds();
+        var observedTimestamp = logRecord.ObservedTimestamp == logRecord.Timestamp ? timestamp
+            : (ulong)logRecord.ObservedTimestamp.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);
+        otlpTagWriterState.WritePosition = ProtobufSerializer.WriteFixed64WithTag(otlpTagWriterState.Buffer, otlpTagWriterState.WritePosition, ProtobufOtlpLogFieldNumberConstants.LogRecord_Observed_Time_Unix_Nano, observedTimestamp);
 
         otlpTagWriterState.WritePosition = ProtobufSerializer.WriteEnumWithTag(otlpTagWriterState.Buffer, otlpTagWriterState.WritePosition, ProtobufOtlpLogFieldNumberConstants.LogRecord_Severity_Number, logRecord.Severity.HasValue ? (int)logRecord.Severity : 0);
 

src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt

@@ -0,0 +1,2 @@
+OpenTelemetry.Logs.LogRecord.ObservedTimestamp.get -> System.DateTime
+OpenTelemetry.Logs.LogRecord.ObservedTimestamp.set -> void

src/OpenTelemetry/Logs/ILogger/OpenTelemetryLogger.cs

@@ -71,6 +71,7 @@ public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Except
             ref var data = ref record.Data;
 
             data.TimestampBacking = DateTime.UtcNow;
+            data.ObservedTimestampBacking = data.TimestampBacking;
 
             SetLogRecordSeverityFields(ref data, logLevel);
 

src/OpenTelemetry/Logs/LogRecord.cs

@@ -51,6 +51,7 @@ internal LogRecord(
         this.Data = new(activity)
         {
             TimestampBacking = timestamp,
+            ObservedTimestampBacking = timestamp,
 
             Body = formattedMessage,
         };
@@ -114,6 +115,20 @@ public DateTime Timestamp
         set => this.Data.Timestamp = value;
     }
 
+    /// <summary>
+    /// Gets or sets the observed timestamp.
+    /// </summary>
+    /// <remarks>
+    /// Note: If <see cref="ObservedTimestamp"/> is set to a value with <see
+    /// cref="DateTimeKind.Local"/> it will be automatically converted to
+    /// UTC using <see cref="DateTime.ToUniversalTime"/>.
+    /// </remarks>
+    public DateTime ObservedTimestamp
+    {
+        get => this.Data.ObservedTimestamp;
+        set => this.Data.ObservedTimestamp = value;
+    }
+
     /// <summary>
     /// Gets or sets the log <see cref="ActivityTraceId"/>.
     /// </summary>

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

@@ -102,6 +102,25 @@ record = default;
         Assert.Equal(now.ToUniversalTime(), record.Timestamp);
     }
 
+    [Fact]
+    public void ObservedTimestampTest()
+    {
+        var nowUtc = DateTime.UtcNow;
+
+        var record = new LogRecordData();
+        Assert.True(record.ObservedTimestamp >= nowUtc);
+
+        record = default;
+        Assert.Equal(DateTime.MinValue, record.ObservedTimestamp);
+
+        var now = DateTime.Now;
+
+        record.ObservedTimestamp = now;
+
+        Assert.Equal(DateTimeKind.Utc, record.ObservedTimestamp.Kind);
+        Assert.Equal(now.ToUniversalTime(), record.ObservedTimestamp);
+    }
+
     [Fact]
     public void SetActivityContextTest()
     {