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 5 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
5 commits
Select commit Hold shift + click to select a range
53853d0
feat: add support for metric data-point flags
herin049 Feb 17, 2026
b74cf8d
update CHANGELOG.md
herin049 Feb 17, 2026
7329b5b
add BREAKING label to changelog entry
herin049 Feb 21, 2026
0da1cc2
update dataclass definitions
herin049 Feb 21, 2026
6291158
fix lint error
herin049 Mar 13, 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 @@ -577,6 +577,8 @@ can cause a deadlock to occur over `logging._lock` in some cases ([#4636](https:
- The exporter's API is not changed
- Add parameters for Distros and configurators to configure autoinstrumentation in addition to existing environment variables.
([#3864](https://github.com/open-telemetry/opentelemetry-python/pull/3864))
- [BREAKING] `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-common`: Add support for metric data-point flags
Copy link
Copy Markdown
Member

@MikeGoldsmith MikeGoldsmith Apr 1, 2026

Choose a reason for hiding this comment

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

This says it's a breaking change, but the PR desc doesn't have the Breaking checkbox.

Is it breaking or just addative?

Copy link
Copy Markdown
Contributor Author

@herin049 herin049 Apr 2, 2026

Choose a reason for hiding this comment

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

I technically changed some field orderings in ExponentialHistogramDataPoint for consistency, so it's a very trivial breaking change.

([#4916](https://github.com/open-telemetry/opentelemetry-python/pull/4916))

## Version 1.24.0/0.45b0 (2024-03-28)

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
34 changes: 31 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,9 @@ 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 +526,9 @@ 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 +660,9 @@ 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 +725,9 @@ 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 +798,9 @@ 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 +871,9 @@ 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 +905,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 +990,9 @@ 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
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
Copy link
Copy Markdown
Member

@MikeGoldsmith MikeGoldsmith Apr 1, 2026

Choose a reason for hiding this comment

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

Do we need this fixme now we're getting defaults?

Copy link
Copy Markdown
Contributor Author

@herin049 herin049 Apr 2, 2026

Choose a reason for hiding this comment

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

Someone has a follow-up PR that addresses this, I'm going to leave the comment for now.

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
Loading