Logs API - initialize LogRecordData.Timestamp with MinValue by Kielek · Pull Request #7045 · open-telemetry/opentelemetry-dotnet

Kielek · 2026-04-08T08:59:35Z

Handles discussions from #6979 related to nullability.

Changes

Logs API - initialize LogRecordData.Timestamp with MinValue
MinValue is equivalent of 0/null value from OTel Spec.

Merge requirement checklist

CONTRIBUTING guidelines followed (license requirements, nullable enabled, static analysis, etc.)
Unit tests added/updated
Appropriate CHANGELOG.md files updated for non-trivial changes
~~[ ] Changes in public API reviewed (if applicable)~~

codecov · 2026-04-08T09:07:41Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.81%. Comparing base (ec8a796) to head (8bff6b4).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7045      +/-   ##
==========================================
- Coverage   89.86%   89.81%   -0.06%     
==========================================
  Files         273      273              
  Lines       13767    13773       +6     
==========================================
- Hits        12372    12370       -2     
- Misses       1395     1403       +8

Flag	Coverage Δ
unittests-Project-Experimental	`89.77% <100.00%> (-0.07%)`	⬇️
unittests-Project-Stable	`89.72% <100.00%> (-0.08%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/OpenTelemetry.Api/Logs/LogRecordData.cs	`100.00% <100.00%> (ø)`
...metry.Exporter.Console/ConsoleLogRecordExporter.cs	`97.10% <100.00%> (+0.04%)`	⬆️
...ementation/Serializer/ProtobufOtlpLogSerializer.cs	`99.26% <100.00%> (+0.02%)`	⬆️
src/OpenTelemetry/Logs/LogRecord.cs	`70.86% <ø> (ø)`

... and 2 files with indirect coverage changes

Kielek · 2026-04-08T09:16:51Z

@juliuskoval, could you please review?

pellared · 2026-04-08T12:45:32Z

+        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();
+        }


Have you considered changing ToUnixTimeNanoseconds (and other extension methods) to return 0 when datetime is min?

Yes, but we should handle timestamp and observed timespan differently, so I would keep as is.

pellared · 2026-04-08T12:48:01Z

+        {
+            // Timestamp was explicitly set: use it for both fields.
+            timeUnixNano = (ulong)logTimestamp.ToUnixTimeNanoseconds();
+            observedTimeUnixNano = timeUnixNano;


Why not always setting observedTimeUnixNano = (ulong)DateTime.UtcNow.ToUnixTimeNanoseconds();?

From https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-observedtimestamp:

This field SHOULD be set once the event is observed by OpenTelemetry.

I am not sure what would be the value of setting the same time for ObservedTimestamp and Timestamp.

Here is what we do in OTel Go: https://github.com/open-telemetry/opentelemetry-go/blob/3157d0a7d9d22c3343838da6b1a691557676072f/sdk/log/logger.go#L116-L119

Setting ObservedTimestamp is addressed in #6979; this PR only addresses nullability of Timestamp if I understand it correctly. Changes from the other PR would allow users to set ObservedTimestamp in the API/SDK.

Julius is right, it is intermittent state and should be changed in the short cadence in #6973.
I hope that both will be merged together. For now, I am keeping existing behavior as much as possible.

juliuskoval · 2026-04-08T16:53:08Z

@juliuskoval, could you please review?

You didn't add changelogs for OpenTelemetry.Exporter.OpenTelemetryProtocol and OpenTelemetry.Exporter.Console, but other than that it looks good to me.

github-actions · 2026-04-17T04:15:14Z

This PR was marked stale due to lack of activity and will be closed in 7 days. Commenting or pushing will instruct the bot to automatically remove the label. This bot runs once per day.

alanwest · 2026-04-28T22:16:39Z

 #pragma warning restore CA1815 // Override equals and operator equals on value types
 {
-    internal DateTime TimestampBacking = DateTime.UtcNow;
+    internal DateTime TimestampBacking = DateTime.MinValue;


My read of the API spec is that timestamp is an optional parameter, but the spec does not lend guidance for what the default value should be. I think one could argue that our current behavior of defaulting to UtcNow is acceptable.

However if we were to change the default value, why DateTime.MinValue? Wouldn't a default value of 1/1/1970 00:00 be better? Someone correct me if I'm wrong, but I believe that's what Java and Go SDKs default to.

My read of the API spec is that timestamp is an optional parameter, but the spec does not lend guidance for what the default value should be.

We could clarify it in the spec. The intention is that the default is "0" when the value is exported via OTLP if no value was explicitly set.
From https://github.com/open-telemetry/opentelemetry-proto/blob/62498ba4f8e268c40e9420ed912e3cc32e11f487/opentelemetry/proto/logs/v1/logs.proto#L139-L142:

// time_unix_nano is the time when the event occurred. // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. // Value of 0 indicates unknown or missing timestamp. fixed64 time_unix_nano = 1;

Alan lets consider this:
https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-timestamp
and https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-observedtimestamp

The first one is marked as fully optional (what is more proto treats its as a nullable, sets to 0).Does not say anything about default.
Observed timestamp is the moment when the OTel sees it first time, and it should be set to the UtcNow.

We are still missing ObservedTimestamp, it will be added in scope of #6979.

Sdk already exposes LogRecord as DateTime non nullable this value (see changes in this file). To do not break this, I considered choosing one value as null/0/equivalent. IMO DateTime.MinValue is the most obvious choice. It was discussed earlier with @pellared, and the Go-lang is doing mostly the same.

The following part is prepared by the Codex, but as I understand the code, it confirms what I stated about go-lang.

Short version: this branch behavior matches Java and Go.

OpenTelemetry defines Timestamp as optional when the source/event time is unknown. ObservedTimestamp should be set once OpenTelemetry observes the event. In OTLP protobuf, time_unix_nano = 0 means unknown or missing timestamp.

Java

Java v1.61.0 keeps the source timestamp unset when the caller does not provide one. The SDK stores timestampEpochNanos as 0 by default, while observedTimestampEpochNanos is filled from the SDK clock if absent.

Go

Go v1.43.0 / logs v0.19.0 behaves similarly. A zero-value log.Record has no source timestamp. The SDK preserves that zero timestamp, fills ObservedTimestamp with time.Now() if it is unset, and the OTLP transform maps a zero timestamp to 0.

Conclusion

This change makes .NET follow the same model:

DateTime.MinValue represents an unset source timestamp.

OTLP exports that as time_unix_nano = 0.

observed_time_unix_nano is still populated when OpenTelemetry observes/serializes the record.

Sources

OTel Logs Data Model

OTLP logs.proto

Java LogRecordBuilder

Java SdkLogRecordBuilder

Go Record

Go SDK logger

Go OTLP log transform

We could clarify it in the spec. The intention is that the default is "0" when the value is exported via OTLP if no value was explicitly set.

I think a clarification in the logs API spec would be beneficial. Both time_unix_nano and observed_time_unix_nano are marked as optional parameters which could lead someone to believe the intent is that they both remain unset if they're not provided. Only if you go read the data model spec can you begin to try and infer what the intended default behavior should be.

OTLP exports that as time_unix_nano = 0

Seemingly silly question, but I think it's important for us to think through: What if the timestamp is set to DateTime.MinValue.AddDays(1);?

What should the OTLP exporter export? The timestamp from the OTLP data model is an unsigned 64 bit integer.

What do we recommend other exporters do like the console export or a custom exporter? Should they export 1/2/0001, or would we recommend a behavior that matches OTLP?

I should note, I'm supportive of changing the default value and I favor matching our behavior to what Java and Go are doing, but the fact we're using a DateTime adds a bit of a wrinkle we just need to think through...

I created open-telemetry/opentelemetry-specification#5075

paulomorgado · 2026-04-29T07:44:18Z

If it's supposed to mean 0/null, why not use DateTime? instead?

Kielek · 2026-04-29T08:12:06Z

If it's supposed to mean 0/null, why not use DateTime? instead?

I think that we are able to bring resonable backward-behavioral compatibility. I do not see possibility for such things for the public contract on the SDK level (already declared as stable).

pellared · 2026-04-29T08:25:46Z

I also think that using DateTime is probably a little more performant (less memory overhead)

github-actions · 2026-05-07T04:24:52Z

This PR was marked stale due to lack of activity and will be closed in 7 days. Commenting or pushing will instruct the bot to automatically remove the label. This bot runs once per day.

Logs API - initialize LogRecordData.Timestamp with MinValue

833135a

changelog

2f945ba

github-actions Bot added the pkg:OpenTelemetry Issues related to OpenTelemetry NuGet package label Apr 8, 2026

sanity check fixes

6ca310e

Kielek marked this pull request as ready for review April 8, 2026 09:16

Kielek requested a review from a team as a code owner April 8, 2026 09:16

pellared reviewed Apr 8, 2026

View reviewed changes

pellared approved these changes Apr 9, 2026

View reviewed changes

Merge branch 'main' into logrecorddata-timestamp

dad842c

github-actions Bot added the Stale Issues and pull requests which have been flagged for closing due to inactivity label Apr 17, 2026

Kielek removed the Stale Issues and pull requests which have been flagged for closing due to inactivity label Apr 17, 2026

Kielek added 2 commits April 17, 2026 06:35

Merge branch 'main' into logrecorddata-timestamp

c6c9a55

Merge branch 'main' into logrecorddata-timestamp

e90c7c8

martincostello approved these changes Apr 24, 2026

View reviewed changes

alanwest reviewed Apr 28, 2026

View reviewed changes

Merge branch 'main' into logrecorddata-timestamp

48d6a07

github-actions Bot added the Stale Issues and pull requests which have been flagged for closing due to inactivity label May 7, 2026

Kielek added keep-open Prevents issues and pull requests being closed as stale and removed Stale Issues and pull requests which have been flagged for closing due to inactivity labels May 7, 2026

Merge branch 'main' into logrecorddata-timestamp

8bff6b4

pellared mentioned this pull request May 7, 2026

[Logs] Clarify default values for optional parameters open-telemetry/opentelemetry-specification#5075

Open

Conversation

Kielek commented Apr 8, 2026

Changes

Merge requirement checklist

Uh oh!

codecov Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Kielek commented Apr 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliuskoval commented Apr 8, 2026

Uh oh!

github-actions Bot commented Apr 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pellared Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Java

Go

Conclusion

Sources

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paulomorgado commented Apr 29, 2026

Uh oh!

Kielek commented Apr 29, 2026

Uh oh!

pellared commented Apr 29, 2026

Uh oh!

github-actions Bot commented May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov Bot commented Apr 8, 2026 •

edited

Loading

pellared Apr 29, 2026 •

edited

Loading