Improve clarity of Metric Signal overview #3900
Conversation
specification/overview.md
Outdated
| recorded using OpenTelemetry API. So user may define to aggregate those | ||
| `Measurement`s and use the context passed alongside to define additional | ||
| attributes of the resulting metric. | ||
| The primary classes for recording raw measurements are `Measure` and `Measurement`. |
There was a problem hiding this comment.
This seems very outdated, the current spec doesn't have a "class named Measure".
There was a problem hiding this comment.
I will take another stab at this and try and better validate the information presented.
There was a problem hiding this comment.
Thanks @jaydeluca! The new commits which you just pushed look much better! 👍
specification/overview.md
Outdated
| the `Metric` define their aggregation type as well as a structure of individual | ||
| measurements or Points. API defines the following types of pre-aggregated | ||
| metrics: | ||
| #### Measurements |
There was a problem hiding this comment.
Maybe link to https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#measurement instead of having an entry here?
specification/overview.md
Outdated
| application that will aggregate those individual measurements into a `Metric`. | ||
| `Measure` is identified by name, description and a unit of values. | ||
| ``` | ||
| +-------------------+ |
There was a problem hiding this comment.
I find this a bit misleading, there are two things: API/SDK components (e.g. Provider, Meter, Instrument) and data (e.g. Measurement).
This might be a better diagram? https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/metrics#programming-model
specification/overview.md
Outdated
| @@ -218,73 +218,83 @@ scenarios. | |||
|
|
|||
| ## Metric Signal | |||
|
|
|||
| OpenTelemetry allows to record raw measurements or metrics with predefined | |||
| aggregation and a [set of attributes](./common/README.md#attribute). | |||
| A metric is a collection of raw measurements that can be aggregated alongside | |||
There was a problem hiding this comment.
I feel this is going to the wrong direction. Metrics in OpenTelemetry are always preaggregated, it cannot be "a collection of raw measurements".
specification/overview.md
Outdated
| `Measurement` describes a single value to be collected for a `Measure`. | ||
| `Measurement` is an empty interface in API surface. This interface is defined in | ||
| SDK. | ||
| An `Instrument` describes the type of the individual values recorded by a library. It |
There was a problem hiding this comment.
Consider borrow something from https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument and link to the definition.
Fixes open-telemetry#3847 ## Changes As discussed in the semantic conventions SIG, this PR aims to clarify stability guarantees provided around well[-known attribute values (aka `enums`) defined by semantic conventions: * Changing an existing `enum` value is a breaking change. * Adding a new value to an `enum` is not a breaking change. ## * [x] Related issues open-telemetry#3847 * [ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) * [ ] Links to the prototypes (when adding or changing features) * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes * [ ] [`spec-compliance-matrix.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) updated if necessary --------- Co-authored-by: Armin Ruech <[email protected]> Co-authored-by: Robert Pająk <[email protected]>
…ns, move views under sdk section
|
i messed up rebasing with intellij, closing and re-opening a new PR (#3916) to remove participants added. Sorry for the noise to those who were just added here |
There is no existing issue, but I am suggesting rewriting some of the Metric signal overview.
Changes
My intention was to keep the information being conveyed the same, but improve the readability.