Skip to content
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

Improve clarity of Metric Signal overview #3900

Closed
wants to merge 9 commits into from
Closed

Improve clarity of Metric Signal overview #3900

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
258f02d
rewrite some of the metric signals overview section
jaydeluca Feb 24, 2024
b713f8f
updates to metric signal based on current spec
jaydeluca Feb 28, 2024
02e7d66
moved sentence
jaydeluca Feb 29, 2024
a243241
erlang metrics: update exemplars support in spec matrix (#3903)
tsloughter Feb 26, 2024
81e06ac
Clarify enum attribute value stability guarantees (#3879)
pyohannes Feb 27, 2024
8fb13cf
Clarify that logs attributes are a superset of standard attributes (#…
pellared Feb 27, 2024
a43f26a
[editorial] Remove implementation detail from Logs Bridge API (#3884)
MrAlias Feb 28, 2024
6ffa599
Clarify metric point (#3906)
reyang Feb 28, 2024
b8d892c
reword some sections, swap out diagram, link out to some other sectio…
jaydeluca Feb 29, 2024
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
46 changes: 23 additions & 23 deletions specification/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,27 +218,27 @@ scenarios.

## Metric Signal

OpenTelemetry allows to record raw measurements or metrics with predefined
aggregation and a [set of attributes](./common/README.md#attribute).
OpenTelemetry allows recording raw measurements or metrics with predefined
aggregations and 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.
Using the OpenTelemetry API to record raw measurements gives end-users the
flexibility to choose the aggregation algorithm for a given metric, as well
as to define its attributes (dimensions). 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 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 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".
Similarly, capturing metrics with predefined aggregation strategies through the
OpenTelemetry API is useful for working with metrics such as CPU and memory usage,
as well as simpler metrics like queue length.

### 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.
The primary classes for recording raw measurements are `Measure` and `Measurement`.
Copy link
Member

Choose a reason for hiding this comment

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

This seems very outdated, the current spec doesn't have a "class named Measure".

Copy link
Member Author

Choose a reason for hiding this comment

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

I will take another stab at this and try and better validate the information presented.

Copy link
Member

Choose a reason for hiding this comment

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

Thanks @jaydeluca! The new commits which you just pushed look much better! 👍

The OpenTelemetry API allows for the recording of a list of `Measurement`s along with
additional context. Users can then aggregate these `Measurement`s and utilize the
accompanying context to define extra attributes for the resulting metric.

#### Measure

Expand All @@ -258,7 +258,7 @@ 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
measurements or Points. The API defines the following types of pre-aggregated
metrics:

- Counter metric to report instantaneous measurement. Counter values can go
Expand All @@ -268,23 +268,23 @@ metrics:
go both up and down. The gauges values can be negative. There are two types of
gauge metric values - `double` and `long`.

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.
The API enables the construction of a `Metric` of a chosen type, while the SDK
outlines how to query the current value of a `Metric` for export.

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.
Each type of `Metric` has its own API for recording values that will be aggregated.
The API supports both push and pull models for setting the `Metric` value.

### 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.

Expand Down
Loading