From b6aaf38a3dad6778f96f8aea3449135f73779fdb Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 9 Jul 2024 16:45:30 +0200 Subject: [PATCH 01/10] Add data point flags to the metric data model --- specification/metrics/data-model.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index e5123622802..60453e196eb 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -412,6 +412,7 @@ in OTLP consist of the following: - Times are specified in Value is UNIX Epoch time in nanoseconds since `00:00:00 UTC on 1 January 1970` - (optional) a set of examplars (see [Exemplars](#exemplars)). + - (optional) Data point flags (see [Data point flags](#data-point-flags)). The aggregation temporality is used to understand the context in which the sum was calculated. When the aggregation temporality is "delta", we expect to have @@ -447,6 +448,7 @@ in OTLP represents a sampled value at a given time. A Gauge stream consists of: first possible moment a measurement could be recorded. This is commonly set to the timestamp when a metric collection system started. - (optional) a set of examplars (see [Exemplars](#exemplars)). + - (optional) Data point flags (see [Data point flags](#data-point-flags)). In OTLP, a point within a Gauge stream represents the last-sampled event for a given time window. @@ -493,6 +495,7 @@ Histograms consist of the following: bucket. - A count of the number of observations that fell within this bucket. - (optional) a set of examplars (see [Exemplars](#exemplars)). + - (optional) Data point flags (see [Data point flags](#data-point-flags)). Like Sums, Histograms also define an aggregation temporality. The picture above denotes Delta temporality where accumulated event counts are reset to zero after reporting @@ -995,6 +998,25 @@ sum. For Gauges, when an exemplar exists, its value was seen at some point within the gauge interval for the same source. +## Data point flags + +**Status**: [Experimental](../document-status.md) + +Certain flags can be applied to denote special data points. A flag can either +be true or false. Currently the following flag is supported. + +### No recorded value + +If this flag is set on a data point, then this data point 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 they were marked stale. It is an equivalent of the [Prometheus staleness marker](https://prometheus.io/docs/prometheus/2.52/querying/basics/#staleness). + +If this flag is set, all other data point properties except attributes, time +stamps, or time windows should be ignored. + +This flags defaults to `false`. + ## Single-Writer **Status**: [Stable](../document-status.md) From be7d7b3776984e5677d9409749f23036a8b8eddb Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 9 Jul 2024 16:51:03 +0200 Subject: [PATCH 02/10] Fix wording --- specification/metrics/data-model.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 60453e196eb..c75cd66cb57 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1002,18 +1002,20 @@ the gauge interval for the same source. **Status**: [Experimental](../document-status.md) -Certain flags can be applied to denote special data points. A flag can either -be true or false. Currently the following flag is supported. +Certain flags can be applied to denote special data points. A flag is a +boolean property which can either be set to `true` or `false`. Currently the +following flag is supported. ### No recorded value If this flag is set on a data point, then this data point 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 they were marked stale. It is an equivalent of the [Prometheus staleness marker](https://prometheus.io/docs/prometheus/2.52/querying/basics/#staleness). +queries after such an indicator was received. It is an equivalent of the +[Prometheus staleness marker](https://prometheus.io/docs/prometheus/2.52/querying/basics/#staleness). If this flag is set, all other data point properties except attributes, time -stamps, or time windows should be ignored. +stamps, or time windows, should be ignored. This flags defaults to `false`. From 6d8c624afa867f56d3d106cfd056b1ffdfa8be2c Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Wed, 10 Jul 2024 13:04:01 +0200 Subject: [PATCH 03/10] Update specification/metrics/data-model.md Co-authored-by: Reiley Yang --- specification/metrics/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index c75cd66cb57..1885d7cacc4 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1002,7 +1002,7 @@ the gauge interval for the same source. **Status**: [Experimental](../document-status.md) -Certain flags can be applied to denote special data points. A flag is a +Certain flags can be applied to denote special data points. A flag is a boolean property which can either be set to `true` or `false`. Currently the following flag is supported. From b416ba480b36239d92dcc426a5bfc1f40432341b Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Wed, 10 Jul 2024 13:06:53 +0200 Subject: [PATCH 04/10] PR comments --- specification/metrics/data-model.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 1885d7cacc4..5f7982b434b 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -41,6 +41,8 @@ aliases: [/docs/reference/specification/metrics/datamodel] + [ExponentialHistogram: Bucket inclusivity](#exponentialhistogram-bucket-inclusivity) * [Summary (Legacy)](#summary-legacy) - [Exemplars](#exemplars) +- [Data point flags](#data-point-flags) + * [No recorded value](#no-recorded-value) - [Single-Writer](#single-writer) - [Temporality](#temporality) - [Resets and Gaps](#resets-and-gaps) From 2c19cf73251669ce68bb2c8b5c7616151c580017 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 12 Jul 2024 09:56:01 +0200 Subject: [PATCH 05/10] Add data point flags to measurement --- specification/metrics/api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 1103869a115..f02f5920fcc 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -1291,6 +1291,7 @@ for the interaction between the API and SDK. * A value * [`Attributes`](../common/README.md#attribute) +* [since 1.35.0] [Data point flags](./data-model.md#data-point-flags) ### Multiple-instrument callbacks From d4a4544f0dfdf7e5dcc61c3594e3410c0177adf2 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 16 Jul 2024 18:18:28 +0200 Subject: [PATCH 06/10] Update release number --- specification/metrics/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index f02f5920fcc..3e84340b80e 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -1291,7 +1291,7 @@ for the interaction between the API and SDK. * A value * [`Attributes`](../common/README.md#attribute) -* [since 1.35.0] [Data point flags](./data-model.md#data-point-flags) +* [since 1.36.0] [Data point flags](./data-model.md#data-point-flags) ### Multiple-instrument callbacks From fdca641f60574c4254a8a09c601375762464deae Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Wed, 17 Jul 2024 18:02:57 +0200 Subject: [PATCH 07/10] Remove API changes --- specification/metrics/api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 3e84340b80e..1103869a115 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -1291,7 +1291,6 @@ for the interaction between the API and SDK. * A value * [`Attributes`](../common/README.md#attribute) -* [since 1.36.0] [Data point flags](./data-model.md#data-point-flags) ### Multiple-instrument callbacks From 9b6b9268f7a50a777d4c00679b03e4191ce5cb44 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 6 Aug 2024 15:18:54 +0200 Subject: [PATCH 08/10] Update specification/metrics/data-model.md --- specification/metrics/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 5f7982b434b..646bad12b1a 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1002,7 +1002,7 @@ the gauge interval for the same source. ## Data point flags -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md) Certain flags can be applied to denote special data points. A flag is a boolean property which can either be set to `true` or `false`. Currently the From 16a2b2a759129121a7df8dadeda7a97041188edd Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 6 Aug 2024 15:27:09 +0200 Subject: [PATCH 09/10] Update specification/metrics/data-model.md Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- specification/metrics/data-model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 646bad12b1a..1df97c7647c 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1012,12 +1012,12 @@ following flag is supported. If this flag is set on a data point, then this data point 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 +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](https://prometheus.io/docs/prometheus/2.52/querying/basics/#staleness). If this flag is set, all other data point properties except attributes, time -stamps, or time windows, should be ignored. +stamps, or time windows, SHOULD be ignored. This flags defaults to `false`. From d6f4c968549bbf8ac01a5e5117487d22319931e3 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 6 Aug 2024 15:27:19 +0200 Subject: [PATCH 10/10] Update specification/metrics/data-model.md Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- specification/metrics/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 1df97c7647c..1f59bfec7ae 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1019,7 +1019,7 @@ queries after such an indicator was received. It is an equivalent of the If this flag is set, all other data point properties except attributes, time stamps, or time windows, SHOULD be ignored. -This flags defaults to `false`. +This flag defaults to `false`. ## Single-Writer