[ImamWahyudiz]

Pull Request: sdk/metrics: assign and encode start_time_unix_nano for Gauge (#5849)

---

Description

Per the MetricReader specification and Start timestamps specification, StartTimeUnixNano rules apply to all metrics according to the MetricReader's configured temporality for the instrument kind, "not just those whose point kinds includes an aggregation temporality field."

Prior to this PR, Gauge and ObservableGauge (LastValue aggregation) omitted start_time_unix_nano:

1. _LastValueAggregation.__init__ omitted start_time_unix_nano.
2. DefaultAggregation._create_aggregation() and LastValueAggregation._create_aggregation() did not forward start_time_unix_nano to _LastValueAggregation.
3. _LastValueAggregation.collect() explicitly assigned start_time_unix_nano=None when creating NumberDataPoint.
4. The OTLP Protobuf encoder (proto/common/_internal/metrics_encoder/__init__.py) and OTLP JSON encoder (json/common/_internal/metrics_encoder/__init__.py) omitted start_time_unix_nano=data_point.start_time_unix_nano when instantiating pb2.NumberDataPoint and JSONNumberDataPoint for Gauge metrics.

Solution

1. opentelemetry-sdk:
   • Updated _LastValueAggregation.__init__ to accept and store start_time_unix_nano: int = 0.
   • Updated DefaultAggregation._create_aggregation() and LastValueAggregation._create_aggregation() to pass start_time_unix_nano into _LastValueAggregation.
   • Updated _LastValueAggregation.collect() to assign start_time_unix_nano=self._start_time_unix_nano to NumberDataPoint.
2. opentelemetry-exporter-otlp-proto-common:
   • Added start_time_unix_nano=data_point.start_time_unix_nano when instantiating pb2.NumberDataPoint for Gauge metrics in _encode_metric().
3. opentelemetry-exporter-otlp-json-common:
   • Added start_time_unix_nano=data_point.start_time_unix_nano in _encode_gauge_data_point().
4. Testing & Tooling:
   • Updated existing aggregation tests in test_aggregation.py to assert start_time_unix_nano.
   • Added test_encode_gauge_with_start_time in test_metrics_encoder.py for Protobuf encoding.
   • Updated make_gauge() in JSON encoder tests and asserted start_time_unix_nano in test_encode_gauge.
   • Added changelog entry .changelog/5849.fixed.

---

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

---

Testing & Verification

1. SDK Metrics Unit & Integration Tests:

   uv run --with pytest pytest opentelemetry-sdk/tests/metrics/

   Result: 337 passed, 11 skipped (OS-specific timer skips on Windows).
2. OTLP Protobuf Encoder Tests:

   uv run --with pytest pytest exporter/opentelemetry-exporter-otlp-proto-common/tests

   Result: 22 passed, 2 subtests passed.
3. OTLP JSON Encoder Tests:

   uv run --with pytest pytest -o pythonpath=exporter/opentelemetry-exporter-otlp-json-common exporter/opentelemetry-exporter-otlp-json-common/tests

   Result: 72 passed, 73 subtests passed.
4. Standalone End-to-End Gauge Pipeline & Encoding Suite:

   uv run --with pytest pytest contributions/opentelemetry_issue_5849/03_test_gauge_start_time.py

   Result: 10 passed in 0.42s (covers synchronous Gauge pipeline, ObservableGauge pipeline, factory propagation, and both encoders).
5. Code Style & Formatting:

   uv run ruff check
   uv run ruff format --check

   Result: All checks passed! 829 files clean.

---

Checklist

• Followed the project's coding standards and style guidelines.
• Added unit tests covering all modified code paths.
• Verified backward compatibility with existing tests and mock objects.
• Passed all linting and formatting checks (ruff check, ruff format).
• Created changelog fragment in .changelog/5849.fixed.
• Self-reviewed the patch for minimal, high-signal diff.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: ImamWahyudiz / name: imamWahyudiz (7dcd1d0)

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-11-05 17:25 UTC

Review the latest changes.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[Dotify71]

Great fix for #5849 Left two small inline notes regarding the changelog filename and default parameter typing. Check them rather than those things i don't see any other issue in the pr :))

[Dotify71]

As per CONTRIBUTING.md, the changelog filename should match the PR number: .changelog/5852.fixed.

[ImamWahyudiz]

Thanks for the correction! renamed .changelog/5849.fixed to .changelog/5852.fixed to match the PR number.

[Dotify71]

Should this default to None (int | None = None) to avoid setting start_time_unix_nano=0 (epoch 0) when no start time is provided?

[ImamWahyudiz]

Good point.
Updated the default and annotation to int | None = None. This avoids defaulting to Unix epoch 0 when unsupplied, while preserving the optional Gauge start time semantics per the specification.

[ImamWahyudiz]

@Dotify71 Thanks for the review! I've spotted the inline notes about the changelog filename and default parameter typing.

[Dotify71]

Thanks for updating both the changelog filename and the default parameter typing so quickly, @ImamWahyudiz
Everything looks very clean and well-aligned with the spec now. LGTM... Thanks