-
Notifications
You must be signed in to change notification settings - Fork 893
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.
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
Improve clarity of Metric Signal overview #3900
Changes from 3 commits
258f02d
b713f8f
02e7d66
a243241
81e06ac
8fb13cf
a43f26a
6ffa599
b8d892c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -22,9 +22,9 @@ weight: 1 | |
* [Links between spans](#links-between-spans) | ||
- [Metric Signal](#metric-signal) | ||
* [Recording raw measurements](#recording-raw-measurements) | ||
+ [Measure](#measure) | ||
+ [Measurement](#measurement) | ||
* [Recording metrics with predefined aggregation](#recording-metrics-with-predefined-aggregation) | ||
+ [Instruments](#instruments) | ||
+ [Measurements](#measurements) | ||
* [Views](#views) | ||
* [Metrics data model and SDK](#metrics-data-model-and-sdk) | ||
- [Log Signal](#log-signal) | ||
* [Data model](#data-model) | ||
|
@@ -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 | ||
a [set of attributes](./common/README.md#attribute). | ||
|
||
Recording raw measurements using OpenTelemetry API allows to defer to end-user | ||
the decision on what aggregation algorithm should be applied for this metric as | ||
well as defining attributes (dimensions). It will be used in client libraries like | ||
gRPC to record raw measurements "server_latency" or "received_bytes". So end | ||
user will decide what type of aggregated values should be collected out of these | ||
raw measurements. It may be simple average or elaborate histogram calculation. | ||
|
||
Recording of metrics with the pre-defined aggregation using OpenTelemetry API is | ||
not less important. It allows to collect values like cpu and memory usage, or | ||
simple metrics like "queue length". | ||
Using the OpenTelemetry API to record raw measurements gives end-users the | ||
flexibility to choose the aggregation algorithm for a given metric. This functionality | ||
is particularly useful in client libraries such as gRPC, where it enables the | ||
recording of raw measurements like "server_latency" or "received_bytes." End-users | ||
then have the autonomy to decide on the aggregation method for these raw measurements, | ||
options for which range from straightforward averages to more complex histogram calculations. | ||
|
||
### Recording raw measurements | ||
|
||
The main classes used to record raw measurements are `Measure` and | ||
`Measurement`. List of `Measurement`s alongside the additional context can be | ||
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. | ||
|
||
#### Measure | ||
The primary components involved in recording raw measurements using the OpenTelemetry | ||
API are `Measurement`, `Instrument` and `Meter`. A `Meter` is obtained from a | ||
`MeterProvider` and used to create `Instrument`s, which are then responsible for capturing | ||
`Measurement`s. | ||
|
||
`Measure` describes the type of the individual values recorded by a library. It | ||
defines a contract between the library exposing the measurements and an | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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 |
||
| MeterProvider | | ||
+-------------------+ | ||
| | ||
+-------------------+ | ||
| Meter | | ||
+-------------------+ | ||
| | ||
+-----------+-----------+ | ||
| | | ||
+-------------------+ +--------------------+ | ||
| Instrument | | Instrument | | ||
| (e.g., Counter) | | (e.g., Histogram) | | ||
+-------------------+ +--------------------+ | ||
| | | ||
+-------------+ +-------------+ | ||
| Measurement | | Measurement | | ||
+-------------+ +-------------+ | ||
+-------------+ +-------------+ | ||
| Measurement | | Measurement | | ||
+-------------+ +-------------+ | ||
``` | ||
|
||
#### Measurement | ||
#### Instruments | ||
|
||
`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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Consider borrow something from https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument and link to the definition. |
||
defines a contract between the library exposing the measurements and an | ||
application that will aggregate those individual measurements into a metric. | ||
An `Instrument` is identified by a name, kind, description and a unit of values. | ||
|
||
### Recording metrics with predefined aggregation | ||
There are several types of metric instruments for specific use cases, such as counters for | ||
incrementing values, gauges for capturing current values, and histograms for capturing | ||
distributions of measurements. Instruments can be synchronous, meaning that they are invoked | ||
inline by application logic, or asynchronous where the user registers a callback | ||
function that is invoked on demand by the SDK. | ||
|
||
The base class for all types of pre-aggregated metrics is called `Metric`. It | ||
defines basic metric properties like a name and attributes. Classes inheriting from | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe link to https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#measurement instead of having an entry here? |
||
|
||
- Counter metric to report instantaneous measurement. Counter values can go | ||
up or stay the same, but can never go down. Counter values cannot be | ||
negative. There are two types of counter metric values - `double` and `long`. | ||
- Gauge metric to report instantaneous measurement of a numeric value. Gauges can | ||
go both up and down. The gauges values can be negative. There are two types of | ||
gauge metric values - `double` and `long`. | ||
A `Measurement` represents a data point for an `Instrument` and is composed of a | ||
value and associated attributes. | ||
|
||
API allows to construct the `Metric` of a chosen type. SDK defines the way to | ||
query the current value of a `Metric` to be exported. | ||
### Views | ||
|
||
Every type of a `Metric` has it's API to record values to be aggregated. API | ||
supports both - push and pull model of setting the `Metric` value. | ||
`View`s are configurations that specify how the data from `Instrument`s should be processed, | ||
aggregated, and exported. They can be applied globally through the `MeterProvider` or more | ||
specifically at the `Meter` level. `View`s allow customization of metric data beyond the default | ||
collection behavior, enabling specific aggregations, transformations, and filtering of metrics. | ||
|
||
### Metrics data model and SDK | ||
|
||
Metrics data model is [specified here](metrics/data-model.md) and is based on | ||
The Metrics data model is [specified here](metrics/data-model.md) and is based on | ||
[metrics.proto](https://github.com/open-telemetry/opentelemetry-proto/blob/master/opentelemetry/proto/metrics/v1/metrics.proto). | ||
This data model defines three semantics: An Event model used by the API, an | ||
in-flight data model used by the SDK and OTLP, and a TimeSeries model which | ||
denotes how exporters should interpret the in-flight model. | ||
|
||
Different exporters have different capabilities (e.g. which data types are | ||
supported) and different constraints (e.g. which characters are allowed in attribute | ||
keys). Metrics is intended to be a superset of what's possible, not a lowest | ||
keys). Metrics is intended to be a superset of what's possible, not the lowest | ||
common denominator that's supported everywhere. All exporters consume data from | ||
Metrics Data Model via a Metric Producer interface defined in OpenTelemetry SDK. | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel this is going to the wrong direction. Metrics in OpenTelemetry are always preaggregated, it cannot be "a collection of raw measurements".