[SDK] Delta temporality: use per-instrument creation time for first interval start_ts (#4144)

Author: thc1006

CHANGELOG.md

@@ -90,6 +90,9 @@ Increment the:
 * [CI] iwyu and clang-tidy: use install_thirdparty.sh for third-party
   [#4136](https://github.com/open-telemetry/opentelemetry-cpp/pull/4136)
 
+* [SDK] Per-instrument creation time as delta first-interval start_ts
+  [#4144](https://github.com/open-telemetry/opentelemetry-cpp/pull/4144)
+
 ## [1.27.0] 2026-05-13
 
 * [RELEASE] Bump main branch to 1.27.0-dev

sdk/include/opentelemetry/sdk/metrics/state/temporal_metric_storage.h

@@ -58,6 +58,12 @@ class TemporalMetricStorage
   const AggregationConfig *aggregation_config_;
   opentelemetry::common::SystemTimestamp last_delta_collection_ts_;
   bool has_last_delta_collection_ts_ = false;
+  // Captured at this storage's construction time. Per the OpenTelemetry
+  // specification, the start_ts of the first delta collection interval MUST be
+  // the creation time of the instrument, NOT the MeterProvider creation time.
+  // See https://github.com/open-telemetry/opentelemetry-specification (logs/metrics
+  // SDK specs) and issue #4062.
+  const opentelemetry::common::SystemTimestamp instrument_creation_ts_;
 };
 }  // namespace metrics
 }  // namespace sdk

sdk/src/metrics/state/temporal_metric_storage.cc

@@ -1,6 +1,7 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#include <chrono>
 #include <list>
 #include <memory>
 #include <mutex>
@@ -34,7 +35,8 @@ TemporalMetricStorage::TemporalMetricStorage(InstrumentDescriptor instrument_des
                                              const AggregationConfig *aggregation_config)
     : instrument_descriptor_(std::move(instrument_descriptor)),
       aggregation_type_(aggregation_type),
-      aggregation_config_(aggregation_config)
+      aggregation_config_(aggregation_config),
+      instrument_creation_ts_(std::chrono::system_clock::now())
 {}
 
 bool TemporalMetricStorage::buildMetrics(CollectorHandle *collector,
@@ -45,9 +47,16 @@ bool TemporalMetricStorage::buildMetrics(CollectorHandle *collector,
                                          nostd::function_ref<bool(MetricData)> callback) noexcept
 {
   std::lock_guard<opentelemetry::common::SpinLockMutex> guard(lock_);
-  opentelemetry::common::SystemTimestamp last_collection_ts = sdk_start_ts;
   AggregationTemporality aggregation_temporarily =
       collector->GetAggregationTemporality(instrument_descriptor_.type_);
+  // Per OTel spec (issue #4062): the start_ts for the first delta collection
+  // interval must be the instrument creation time, not the MeterProvider
+  // start time (which is what sdk_start_ts carries). For cumulative, sdk_start_ts
+  // is acceptable per spec ("creation of the instrument or the timestamp from
+  // when the SDK was started, whichever happened first").
+  opentelemetry::common::SystemTimestamp last_collection_ts =
+      (aggregation_temporarily == AggregationTemporality::kDelta) ? instrument_creation_ts_
+                                                                  : sdk_start_ts;
 
   // Fast path for single collector with delta temporality and counter, updown-counter, histogram
   // This path doesn't need to aggregated-with/contribute-to the unreported_metric_, as there is
@@ -56,7 +65,7 @@ bool TemporalMetricStorage::buildMetrics(CollectorHandle *collector,
   {
     if (!has_last_delta_collection_ts_)
     {
-      last_delta_collection_ts_     = sdk_start_ts;
+      last_delta_collection_ts_     = instrument_creation_ts_;
       has_last_delta_collection_ts_ = true;
     }
     // If no metrics, early return

sdk/test/metrics/sync_metric_storage_counter_test.cc

@@ -13,6 +13,7 @@
 #include "common.h"
 
 #include "opentelemetry/common/key_value_iterable_view.h"
+#include "opentelemetry/common/timestamp.h"
 #include "opentelemetry/context/context.h"
 #include "opentelemetry/nostd/function_ref.h"
 #include "opentelemetry/nostd/span.h"
@@ -379,10 +380,121 @@ TEST(SyncMetricStorageTest, DeltaCounterStartTimestampTracksEmptyCycles)
   // Check that the fast path correctly preserved the timestamp from the empty
   // collection cycle (cycle 2)
   EXPECT_EQ(metric_cycle3.start_ts, collection_ts2);
-  EXPECT_EQ(metric_cycle1.start_ts, sdk_start_ts);
+  // Per OTel spec (#4062), the first delta interval's start_ts is the
+  // instrument's creation time (captured at storage construction above), not
+  // the sdk_start_ts that the MeterProvider would otherwise pass in. Storage
+  // was constructed before sdk_start_ts was sampled, so the start_ts must be
+  // less-or-equal to sdk_start_ts. SystemTimestamp does not define ordering
+  // operators directly, so compare via time_since_epoch().
+  EXPECT_LE(metric_cycle1.start_ts.time_since_epoch(), sdk_start_ts.time_since_epoch());
   EXPECT_EQ(metric_cycle1.end_ts, collection_ts1);
   EXPECT_EQ(metric_cycle3.end_ts, collection_ts3);
 }
+
+TEST(SyncMetricStorageTest, DeltaCounterFirstIntervalUsesInstrumentCreationTime)
+{
+  // Spec-compliance test for issue #4062: the start_ts of the first delta
+  // collection interval MUST be the per-instrument creation time, NOT the
+  // MeterProvider/SDK start time. Simulate a MeterProvider that was created
+  // long before the instrument by passing an artificial sdk_start_ts that is
+  // strictly earlier than the storage's construction time.
+  InstrumentDescriptor instr_desc = {"name", "desc", "1unit", InstrumentType::kCounter,
+                                     InstrumentValueType::kLong};
+  std::shared_ptr<DefaultAttributesProcessor> default_attributes_processor{
+      new DefaultAttributesProcessor{}};
+
+  auto before_creation = std::chrono::system_clock::now();
+  opentelemetry::sdk::metrics::SyncMetricStorage storage(
+      instr_desc, AggregationType::kSum, default_attributes_processor,
+#ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
+      ExemplarFilterType::kAlwaysOff, ExemplarReservoir::GetNoExemplarReservoir(),
+#endif
+      nullptr);
+  auto after_creation = std::chrono::system_clock::now();
+
+  // sdk_start_ts is intentionally well before storage construction.
+  auto sdk_start_ts  = before_creation - std::chrono::seconds(60);
+  auto collection_ts = after_creation + std::chrono::seconds(1);
+
+  std::map<std::string, std::string> attributes = {{"RequestType", "GET"}};
+  std::shared_ptr<CollectorHandle> collector(
+      new MockCollectorHandle(AggregationTemporality::kDelta));
+  std::vector<std::shared_ptr<CollectorHandle>> collectors;
+  collectors.push_back(collector);
+
+  storage.RecordLong(10, KeyValueIterableView<std::map<std::string, std::string>>(attributes),
+                     opentelemetry::context::Context{});
+
+  MetricData metric_data;
+  bool collected = false;
+  storage.Collect(collector.get(), collectors, sdk_start_ts, collection_ts,
+                  [&](const MetricData &md) {
+                    metric_data = md;
+                    collected   = true;
+                    return true;
+                  });
+  ASSERT_TRUE(collected);
+
+  // start_ts must be the instrument creation time (between the two clock
+  // samples taken around the storage constructor), and strictly greater than
+  // the simulated MeterProvider start time. SystemTimestamp does not define
+  // ordering operators directly; compare via time_since_epoch() durations.
+  EXPECT_GE(metric_data.start_ts.time_since_epoch(), before_creation.time_since_epoch());
+  EXPECT_LE(metric_data.start_ts.time_since_epoch(), after_creation.time_since_epoch());
+  EXPECT_GT(metric_data.start_ts.time_since_epoch(), sdk_start_ts.time_since_epoch());
+  EXPECT_EQ(metric_data.end_ts, collection_ts);
+}
+
+TEST(SyncMetricStorageTest, DeltaCounterMultiCollectorFirstIntervalUsesInstrumentCreationTime)
+{
+  // Slow-path counterpart of DeltaCounterFirstIntervalUsesInstrumentCreationTime.
+  // With more than one collector, buildMetrics takes the slow path; that path
+  // must also use instrument_creation_ts_ as the start_ts for the first delta
+  // collection interval (issue #4062 explicitly mentions both paths).
+  InstrumentDescriptor instr_desc = {"name", "desc", "1unit", InstrumentType::kCounter,
+                                     InstrumentValueType::kLong};
+  std::shared_ptr<DefaultAttributesProcessor> default_attributes_processor{
+      new DefaultAttributesProcessor{}};
+
+  auto before_creation = std::chrono::system_clock::now();
+  opentelemetry::sdk::metrics::SyncMetricStorage storage(
+      instr_desc, AggregationType::kSum, default_attributes_processor,
+#ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
+      ExemplarFilterType::kAlwaysOff, ExemplarReservoir::GetNoExemplarReservoir(),
+#endif
+      nullptr);
+  auto after_creation = std::chrono::system_clock::now();
+
+  auto sdk_start_ts  = before_creation - std::chrono::seconds(60);
+  auto collection_ts = after_creation + std::chrono::seconds(1);
+
+  std::map<std::string, std::string> attributes = {{"RequestType", "GET"}};
+  // Two collectors force collectors.size() > 1, which bypasses the fast path.
+  std::shared_ptr<CollectorHandle> collector_a(
+      new MockCollectorHandle(AggregationTemporality::kDelta));
+  std::shared_ptr<CollectorHandle> collector_b(
+      new MockCollectorHandle(AggregationTemporality::kDelta));
+  std::vector<std::shared_ptr<CollectorHandle>> collectors{collector_a, collector_b};
+
+  storage.RecordLong(10, KeyValueIterableView<std::map<std::string, std::string>>(attributes),
+                     opentelemetry::context::Context{});
+
+  MetricData metric_data;
+  bool collected = false;
+  storage.Collect(collector_a.get(), collectors, sdk_start_ts, collection_ts,
+                  [&](const MetricData &md) {
+                    metric_data = md;
+                    collected   = true;
+                    return true;
+                  });
+  ASSERT_TRUE(collected);
+
+  // Same assertion shape as the fast-path test.
+  EXPECT_GE(metric_data.start_ts.time_since_epoch(), before_creation.time_since_epoch());
+  EXPECT_LE(metric_data.start_ts.time_since_epoch(), after_creation.time_since_epoch());
+  EXPECT_GT(metric_data.start_ts.time_since_epoch(), sdk_start_ts.time_since_epoch());
+  EXPECT_EQ(metric_data.end_ts, collection_ts);
+}
 INSTANTIATE_TEST_SUITE_P(WritableMetricStorageTestDouble,
                          WritableMetricStorageTestFixture,
                          ::testing::Values(AggregationTemporality::kCumulative,