Skip to content

feat: add support for metric data-point flags #4916

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
herin049 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat: add support for metric data-point flags #4916

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8ceb131
feat: add support for metric data-point flags
herin049 Feb 17, 2026
f10a904
update CHANGELOG.md
herin049 Feb 17, 2026
802667b
add BREAKING label to changelog entry
herin049 Feb 21, 2026
6f4b5bb
update dataclass definitions
herin049 Feb 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
([#4709](https://github.com/open-telemetry/opentelemetry-python/pull/4709))
- Implement experimental TracerConfigurator
([#4861](https://github.com/open-telemetry/opentelemetry-python/pull/4861))
- [BREAKING] `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-common`: Add support for metric data-point flags
([#4916](https://github.com/open-telemetry/opentelemetry-python/pull/4916))

## Version 1.39.0/0.60b0 (2025-12-03)

Expand Down
5 changes: 4 additions & 1 deletion ...common/src/opentelemetry/exporter/otlp/proto/common/_internal/metrics_encoder/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,7 @@ def _encode_metric(metric, pb2_metric):
attributes=_encode_attributes(data_point.attributes),
time_unix_nano=data_point.time_unix_nano,
exemplars=_encode_exemplars(data_point.exemplars),
flags=int(data_point.flags),
)
if isinstance(data_point.value, int):
pt.as_int = data_point.value
Expand All @@ -272,6 +273,7 @@ def _encode_metric(metric, pb2_metric):
explicit_bounds=data_point.explicit_bounds,
max=data_point.max,
min=data_point.min,
flags=int(data_point.flags),
)
pb2_metric.histogram.aggregation_temporality = (
metric.data.aggregation_temporality
Expand All @@ -285,6 +287,7 @@ def _encode_metric(metric, pb2_metric):
start_time_unix_nano=data_point.start_time_unix_nano,
time_unix_nano=data_point.time_unix_nano,
exemplars=_encode_exemplars(data_point.exemplars),
flags=int(data_point.flags),
)
if isinstance(data_point.value, int):
pt.as_int = data_point.value
Expand Down Expand Up @@ -328,9 +331,9 @@ def _encode_metric(metric, pb2_metric):
zero_count=data_point.zero_count,
positive=positive,
negative=negative,
flags=data_point.flags,
max=data_point.max,
min=data_point.min,
flags=int(data_point.flags),
)
pb2_metric.exponential_histogram.aggregation_temporality = (
metric.data.aggregation_temporality
Expand Down
20 changes: 17 additions & 3 deletions exporter/opentelemetry-exporter-otlp-proto-common/tests/test_metrics_encoder.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
from opentelemetry.sdk.metrics.export import (
AggregationTemporality,
Buckets,
DataPointFlags,
ExponentialHistogramDataPoint,
HistogramDataPoint,
Metric,
Expand Down Expand Up @@ -91,6 +92,7 @@ class TestOTLPMetricsEncoder(unittest.TestCase):
explicit_bounds=[10.0, 20.0],
min=8,
max=18,
flags=DataPointFlags.get_default(),
)
],
aggregation_temporality=AggregationTemporality.DELTA,
Expand All @@ -112,7 +114,13 @@ def test_encode_sum_int(self):
version="first_version",
schema_url="instrumentation_scope_schema_url",
),
metrics=[_generate_sum("sum_int", 33)],
metrics=[
_generate_sum(
"sum_int",
33,
flags=DataPointFlags.get_default(),
)
],
schema_url="instrumentation_scope_schema_url",
)
],
Expand Down Expand Up @@ -163,6 +171,7 @@ def test_encode_sum_int(self):
start_time_unix_nano=1641946015139533244,
time_unix_nano=1641946016139533244,
as_int=33,
flags=int(DataPointFlags.get_default()),
)
],
aggregation_temporality=AggregationTemporality.CUMULATIVE,
Expand Down Expand Up @@ -515,6 +524,7 @@ def test_encode_histogram(self):
],
max=18.0,
min=8.0,
flags=int(DataPointFlags.get_default()),
)
],
aggregation_temporality=AggregationTemporality.DELTA,
Expand Down Expand Up @@ -646,6 +656,7 @@ def test_encode_multiple_scope_histogram(self):
],
max=18.0,
min=8.0,
flags=int(DataPointFlags.get_default()),
)
],
aggregation_temporality=AggregationTemporality.DELTA,
Expand Down Expand Up @@ -708,6 +719,7 @@ def test_encode_multiple_scope_histogram(self):
],
max=18.0,
min=8.0,
flags=int(DataPointFlags.get_default()),
)
],
aggregation_temporality=AggregationTemporality.DELTA,
Expand Down Expand Up @@ -778,6 +790,7 @@ def test_encode_multiple_scope_histogram(self):
],
max=18.0,
min=8.0,
flags=int(DataPointFlags.get_default()),
)
],
aggregation_temporality=AggregationTemporality.DELTA,
Expand Down Expand Up @@ -848,6 +861,7 @@ def test_encode_multiple_scope_histogram(self):
],
max=18.0,
min=8.0,
flags=int(DataPointFlags.get_default()),
)
],
aggregation_temporality=AggregationTemporality.DELTA,
Expand Down Expand Up @@ -879,7 +893,7 @@ def test_encode_exponential_histogram(self):
zero_count=5,
positive=Buckets(offset=6, bucket_counts=[7, 8]),
negative=Buckets(offset=9, bucket_counts=[10, 11]),
flags=12,
flags=DataPointFlags.get_default(),
min=13.0,
max=14.0,
)
Expand Down Expand Up @@ -964,7 +978,7 @@ def test_encode_exponential_histogram(self):
offset=9,
bucket_counts=[10, 11],
),
flags=12,
flags=int(DataPointFlags.get_default()),
exemplars=[],
min=13.0,
max=14.0,
Expand Down
9 changes: 5 additions & 4 deletions opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/aggregation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@
from opentelemetry.sdk.metrics._internal.measurement import Measurement
from opentelemetry.sdk.metrics._internal.point import Buckets as BucketsPoint
from opentelemetry.sdk.metrics._internal.point import (
DataPointFlags,
ExponentialHistogramDataPoint,
HistogramDataPoint,
NumberDataPoint,
Expand Down Expand Up @@ -887,10 +888,10 @@ def collect(
offset=value_negative.offset,
bucket_counts=(value_negative.get_offset_counts()),
),
# FIXME: Find the right value for flags
flags=0,
min=min_,
max=max_,
# FIXME: Find the right value for flags
Copy link
Contributor

@tammy-baylis-swi tammy-baylis-swi Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the new get_default, are the Fixme still needed?

Copy link
Contributor Author

@herin049 herin049 Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if there is additional work to be done here for determining what exactly the flags should be set to, so I have opted to leave the comment here.

flags=DataPointFlags.get_default(),
)

# Here collection_temporality is CUMULATIVE.
Expand Down Expand Up @@ -1055,10 +1056,10 @@ def collect(
self._previous_value_negative.get_offset_counts()
),
),
# FIXME: Find the right value for flags
flags=0,
min=self._previous_min,
max=self._previous_max,
# FIXME: Find the right value for flags
flags=DataPointFlags.get_default(),
)

return None
Expand Down
34 changes: 33 additions & 1 deletion opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/point.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,36 @@
from opentelemetry.util.types import Attributes


class DataPointFlags(int):
"""A bitmask that represents options specific to the data point.

The only supported option is the "no recorded value" flag (``0x01``). If
set, this flag reflects explicitly missing data in a series. It serves as
an indicator that a previously present timeseries was removed and that
this timeseries SHOULD NOT be returned in queries after such an indicator
was received. It is an equivalent of the Prometheus staleness marker.

If this flag is set, all other data point properties except attributes,
time stamps, or time windows, SHOULD be ignored.

See the `OpenTelemetry Data Point Flags`_ spec for details.

.. _OpenTelemetry Data Point Flags:
https://opentelemetry.io/docs/specs/otel/metrics/data-model/#data-point-flags
"""

DEFAULT = 0x00
NO_RECORDED_VALUE = 0x01

@classmethod
def get_default(cls) -> "DataPointFlags":
return cls(cls.DEFAULT)

@property
def no_recorded_value(self) -> bool:
return bool(self & self.NO_RECORDED_VALUE)


@dataclass(frozen=True)
class NumberDataPoint:
"""Single data point in a timeseries that describes the time-varying scalar
Expand All @@ -37,6 +67,7 @@ class NumberDataPoint:
time_unix_nano: int
value: Union[int, float]
exemplars: Sequence[Exemplar] = field(default_factory=list)
flags: DataPointFlags = DataPointFlags.get_default()

def to_json(self, indent: Optional[int] = 4) -> str:
return dumps(asdict(self), indent=indent)
Expand All @@ -58,6 +89,7 @@ class HistogramDataPoint:
min: float
max: float
exemplars: Sequence[Exemplar] = field(default_factory=list)
flags: DataPointFlags = DataPointFlags.get_default()

def to_json(self, indent: Optional[int] = 4) -> str:
return dumps(asdict(self), indent=indent)
Expand Down Expand Up @@ -85,10 +117,10 @@ class ExponentialHistogramDataPoint:
zero_count: int
positive: Buckets
negative: Buckets
flags: int
min: float
max: float
exemplars: Sequence[Exemplar] = field(default_factory=list)
flags: DataPointFlags = DataPointFlags.get_default()

def to_json(self, indent: Optional[int] = 4) -> str:
return dumps(asdict(self), indent=indent)
Expand Down
2 changes: 2 additions & 0 deletions opentelemetry-sdk/src/opentelemetry/sdk/metrics/export/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
# The point module is not in the export directory to avoid a circular import.
from opentelemetry.sdk.metrics._internal.point import ( # noqa: F401
Buckets,
DataPointFlags,
DataPointT,
DataT,
ExponentialHistogram,
Expand All @@ -52,6 +53,7 @@
"MetricExportResult",
"MetricReader",
"PeriodicExportingMetricReader",
"DataPointFlags",
"DataPointT",
"DataT",
"ExponentialHistogram",
Expand Down
35 changes: 29 additions & 6 deletions opentelemetry-sdk/tests/metrics/test_point.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
from opentelemetry.sdk.metrics.export import (
AggregationTemporality,
Buckets,
DataPointFlags,
ExponentialHistogram,
ExponentialHistogramDataPoint,
Gauge,
Expand Down Expand Up @@ -66,15 +67,16 @@ def setUpClass(cls):
time_unix_nano=2,
value=3.3,
)
cls.number_data_point_0_str = f'{{"attributes": {cls.attributes_0_str}, "start_time_unix_nano": 1, "time_unix_nano": 2, "value": 3.3, "exemplars": []}}'
cls.number_data_point_0_str = f'{{"attributes": {cls.attributes_0_str}, "start_time_unix_nano": 1, "time_unix_nano": 2, "value": 3.3, "exemplars": [], "flags": {DataPointFlags.get_default()}}}'

cls.number_data_point_1 = NumberDataPoint(
attributes=cls.attributes_1,
start_time_unix_nano=2,
time_unix_nano=3,
value=4.4,
flags=DataPointFlags(DataPointFlags.NO_RECORDED_VALUE),
)
cls.number_data_point_1_str = f'{{"attributes": {cls.attributes_1_str}, "start_time_unix_nano": 2, "time_unix_nano": 3, "value": 4.4, "exemplars": []}}'
cls.number_data_point_1_str = f'{{"attributes": {cls.attributes_1_str}, "start_time_unix_nano": 2, "time_unix_nano": 3, "value": 4.4, "exemplars": [], "flags": {DataPointFlags.NO_RECORDED_VALUE}}}'

cls.histogram_data_point_0 = HistogramDataPoint(
attributes=cls.attributes_0,
Expand All @@ -87,7 +89,7 @@ def setUpClass(cls):
min=0.2,
max=3.3,
)
cls.histogram_data_point_0_str = f'{{"attributes": {cls.attributes_0_str}, "start_time_unix_nano": 1, "time_unix_nano": 2, "count": 3, "sum": 3.3, "bucket_counts": [1, 1, 1], "explicit_bounds": [0.1, 1.2, 2.3, 3.4], "min": 0.2, "max": 3.3, "exemplars": []}}'
cls.histogram_data_point_0_str = f'{{"attributes": {cls.attributes_0_str}, "start_time_unix_nano": 1, "time_unix_nano": 2, "count": 3, "sum": 3.3, "bucket_counts": [1, 1, 1], "explicit_bounds": [0.1, 1.2, 2.3, 3.4], "min": 0.2, "max": 3.3, "exemplars": [], "flags": {DataPointFlags.get_default()}}}'

cls.histogram_data_point_1 = HistogramDataPoint(
attributes=cls.attributes_1,
Expand All @@ -99,8 +101,9 @@ def setUpClass(cls):
explicit_bounds=[1.2, 2.3, 3.4, 4.5],
min=0.3,
max=4.4,
flags=DataPointFlags(DataPointFlags.NO_RECORDED_VALUE),
)
cls.histogram_data_point_1_str = f'{{"attributes": {cls.attributes_1_str}, "start_time_unix_nano": 2, "time_unix_nano": 3, "count": 4, "sum": 4.4, "bucket_counts": [2, 1, 1], "explicit_bounds": [1.2, 2.3, 3.4, 4.5], "min": 0.3, "max": 4.4, "exemplars": []}}'
cls.histogram_data_point_1_str = f'{{"attributes": {cls.attributes_1_str}, "start_time_unix_nano": 2, "time_unix_nano": 3, "count": 4, "sum": 4.4, "bucket_counts": [2, 1, 1], "explicit_bounds": [1.2, 2.3, 3.4, 4.5], "min": 0.3, "max": 4.4, "exemplars": [], "flags": {DataPointFlags.NO_RECORDED_VALUE}}}'

cls.exp_histogram_data_point_0 = ExponentialHistogramDataPoint(
attributes=cls.attributes_0,
Expand All @@ -112,11 +115,27 @@ def setUpClass(cls):
zero_count=0,
positive=Buckets(offset=0, bucket_counts=[1]),
negative=Buckets(offset=0, bucket_counts=[0]),
flags=0,
min=10,
max=10,
flags=DataPointFlags.get_default(),
)
cls.exp_histogram_data_point_0_str = f'{{"attributes": {cls.attributes_0_str}, "start_time_unix_nano": 1, "time_unix_nano": 2, "count": 1, "sum": 10, "scale": 1, "zero_count": 0, "positive": {{"offset": 0, "bucket_counts": [1]}}, "negative": {{"offset": 0, "bucket_counts": [0]}}, "flags": 0, "min": 10, "max": 10, "exemplars": []}}'
cls.exp_histogram_data_point_0_str = f'{{"attributes": {cls.attributes_0_str}, "start_time_unix_nano": 1, "time_unix_nano": 2, "count": 1, "sum": 10, "scale": 1, "zero_count": 0, "positive": {{"offset": 0, "bucket_counts": [1]}}, "negative": {{"offset": 0, "bucket_counts": [0]}}, "min": 10, "max": 10, "exemplars": [], "flags": {DataPointFlags.get_default()}}}'

cls.exp_histogram_data_point_1 = ExponentialHistogramDataPoint(
attributes=cls.attributes_1,
start_time_unix_nano=2,
time_unix_nano=3,
count=2,
sum=20,
scale=2,
zero_count=1,
positive=Buckets(offset=0, bucket_counts=[1]),
negative=Buckets(offset=0, bucket_counts=[1]),
min=10,
max=20,
flags=DataPointFlags(DataPointFlags.NO_RECORDED_VALUE),
)
cls.exp_histogram_data_point_1_str = f'{{"attributes": {cls.attributes_1_str}, "start_time_unix_nano": 2, "time_unix_nano": 3, "count": 2, "sum": 20, "scale": 2, "zero_count": 1, "positive": {{"offset": 0, "bucket_counts": [1]}}, "negative": {{"offset": 0, "bucket_counts": [1]}}, "min": 10, "max": 20, "exemplars": [], "flags": {DataPointFlags.NO_RECORDED_VALUE}}}'

cls.sum_0 = Sum(
data_points=[cls.number_data_point_0, cls.number_data_point_1],
Expand Down Expand Up @@ -238,6 +257,10 @@ def test_exp_histogram_data_point(self):
self.exp_histogram_data_point_0.to_json(indent=None),
self.exp_histogram_data_point_0_str,
)
self.assertEqual(
self.exp_histogram_data_point_1.to_json(indent=None),
self.exp_histogram_data_point_1_str,
)

def test_sum(self):
self.assertEqual(self.sum_0.to_json(indent=None), self.sum_0_str)
Expand Down
Loading