From b064c8088b90af81f9db1c7bc7ca65259e56f9eb Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 5 Nov 2021 12:28:36 -0700 Subject: [PATCH 1/5] clarify Metric data type --- specification/metrics/sdk.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 533d1f13863..f934fdbae8e 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -728,8 +728,32 @@ are being sent to. **Parameters:** -`batch` - a batch of `Metrics`. The exact data type of the batch is language -specific, typically it is some kind of list. +`batch` - a batch of `Metric`s. The exact data type of the batch is language +specific, typically it is some kind of list. The exact type of `Metric` is +language specific, and is typically optimized for high performance. Here are +some examples: + +```text + +--------+ +--------+ +--------+ +Batch: | Metric | | Metric | ... | Metric | + +---+----+ +--------+ +--------+ + | + +--> name, unit, description, meter information, ... + | + | +-------------+ +-------------+ +-------------+ + +--> MetricPoints: | MetricPoint | | MetricPoint | ... | MetricPoint | + +-----+-------+ +-------------+ +-------------+ + | + +--> timestamps, dimensions, value (or buckets), exemplars, ... +``` + +Refer to the [Metric points](./datamodel.md#metric-points) section from the +Metrics Data Model specification for more details. + +Note: it is highly recommended that implementors design the `Metric` data type +_based on_ the [Data Model](./datamodel.md), rather than directly use the data +types generated from the proto files (as the types generated from proto files +are not guaranteed to be backward compatible). Returns: `ExportResult` From 216b9ab9dabb34eacbf91454bf915da9709a4b31 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 5 Nov 2021 12:29:32 -0700 Subject: [PATCH 2/5] minor wording adjustment --- specification/metrics/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f934fdbae8e..134216a42f9 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -752,8 +752,8 @@ Metrics Data Model specification for more details. Note: it is highly recommended that implementors design the `Metric` data type _based on_ the [Data Model](./datamodel.md), rather than directly use the data -types generated from the proto files (as the types generated from proto files -are not guaranteed to be backward compatible). +types generated from the proto files (because the types generated from proto +files are not guaranteed to be backward compatible). Returns: `ExportResult` From a2c415e632997c02fa2eede76fbb4115a5043119 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 5 Nov 2021 19:39:57 -0700 Subject: [PATCH 3/5] Update specification/metrics/sdk.md Co-authored-by: Cijo Thomas --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 134216a42f9..f3912f299c2 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -752,7 +752,7 @@ Metrics Data Model specification for more details. Note: it is highly recommended that implementors design the `Metric` data type _based on_ the [Data Model](./datamodel.md), rather than directly use the data -types generated from the proto files (because the types generated from proto +types generated from the [proto files](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto) (because the types generated from proto files are not guaranteed to be backward compatible). Returns: `ExportResult` From bfcc8113b746448644fd1017b67f6fb593dfae4e Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 5 Nov 2021 19:40:32 -0700 Subject: [PATCH 4/5] rewrap --- specification/metrics/sdk.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f3912f299c2..d49ff0ecf35 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -752,8 +752,10 @@ Metrics Data Model specification for more details. Note: it is highly recommended that implementors design the `Metric` data type _based on_ the [Data Model](./datamodel.md), rather than directly use the data -types generated from the [proto files](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto) (because the types generated from proto -files are not guaranteed to be backward compatible). +types generated from the [proto +files](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto) +(because the types generated from proto files are not guaranteed to be backward +compatible). Returns: `ExportResult` From 7eeede927f0afcc6c740c44e01fe770dad3166aa Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 15 Nov 2021 10:15:47 -0800 Subject: [PATCH 5/5] improve wording --- specification/metrics/sdk.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index d49ff0ecf35..3b3f603d7d0 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -708,12 +708,12 @@ A Push Metric Exporter MUST support the following functions: ##### Export(batch) -Exports a batch of `Metrics`. Protocol exporters that will implement this -function are typically expected to serialize and transmit the data to the -destination. +Exports a batch of [Metric points](./datamodel.md#metric-points). Protocol +exporters that will implement this function are typically expected to serialize +and transmit the data to the destination. The SDK MUST provide a way for the exporter to get the [Meter](./api.md#meter) -information (e.g. name, version, etc.) associated with each `Metric`. +information (e.g. name, version, etc.) associated with each `Metric point`. `Export` will never be called concurrently for the same exporter instance. `Export` can be called again only after the current call returns. @@ -728,10 +728,10 @@ are being sent to. **Parameters:** -`batch` - a batch of `Metric`s. The exact data type of the batch is language -specific, typically it is some kind of list. The exact type of `Metric` is -language specific, and is typically optimized for high performance. Here are -some examples: +`batch` - a batch of `Metric point`s. The exact data type of the batch is +language specific, typically it is some kind of list. The exact type of `Metric +point` is language specific, and is typically optimized for high performance. +Here are some examples: ```text +--------+ +--------+ +--------+