Skip to content

Commit

Permalink
Merge branch 'main' into stabilize-add-link
Browse files Browse the repository at this point in the history
  • Loading branch information
@carlosalberto
carlosalberto committed Mar 6, 2024
2 parents bd2f3ea + 4f71c16 commit 33dbeb6
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 53 deletions.
35 changes: 34 additions & 1 deletion specification/common/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ path_base_for_github_subdir:
<!-- toc -->

- [Attribute](#attribute)
* [Standard Attribute](#standard-attribute)
* [Attribute Limits](#attribute-limits)
+ [Configurable Parameters](#configurable-parameters)
+ [Exempt Entities](#exempt-entities)
Expand All @@ -33,7 +34,7 @@ An `Attribute` is a key-value pair, which MUST have the following properties:

- The attribute key MUST be a non-`null` and non-empty string.
- Case sensitivity of keys is preserved. Keys that differ in casing are treated as distinct keys.
- The attribute value is either:
- The attribute value is either[1]:
- A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer.
- An array of primitive type values. The array MUST be homogeneous,
i.e., it MUST NOT contain values of different types.
Expand Down Expand Up @@ -65,6 +66,38 @@ See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/b
See [this document](attribute-type-mapping.md) to find out how to map values obtained
outside OpenTelemetry into OpenTelemetry attribute values.

**[1]**: NOTE: extending the set of attribute value types is a breaking change.
This was decided after extensive debate, with arguments as follows:

* Limiting the types of attribute values to a set which has proved sufficient
during several years of OpenTelemetry's development is a useful guardrail for
design. In taking additional value types off the table, we narrow the solution
space and have more productive design conversations.
* We proposed extending support for complex value types and received significant
pushback. Removing the bounds significantly increases the burden on data
consumers. Adding additional simple value types doesn't cause the same level
of burden, but these can be encoded using existing primitive types. For
example, datetime can be encoded as a string or 64 bit integer.
* Limiting attribute value types to primitives and arrays of primitives supports
OpenTelemetry's intent that attributes are metadata, and facilitates the
ability for data consumers to create search indexes and perform other
statistical analysis.

### Standard Attribute

Attributes are used in various places throughout the OpenTelemetry data model.
We designate the [previous attribute section](#attribute) as the standard
attribute definition, in order to facilitate more intuitive and consistent API /
SDK design.

The standard attribute definition SHOULD be used to represent attributes in data
modeling unless there is a strong justification to diverge. For example, the Log
Data Model has an extended [attributes](../logs/data-model.md#field-attributes)
definition allowing values of [type `Any`](../logs/data-model.md#type-any). This
reflects that LogRecord attributes are expected to model data produced from
external log APIs, which do not necessarily have the same value type
restrictions as the standard attribute definition.

### Attribute Limits

Execution of erroneous code can result in unintended attributes. If there are no
Expand Down
98 changes: 46 additions & 52 deletions specification/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +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)
* [Metrics data model and SDK](#metrics-data-model-and-sdk)
+ [Views](#views)
- [Log Signal](#log-signal)
* [Data model](#data-model)
- [Baggage Signal](#baggage-signal)
Expand Down Expand Up @@ -218,73 +217,61 @@ 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.

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

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

#### Measurement

`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.
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 an `Instrument`, which is then responsible for capturing
[measurements](metrics/api.md#measurement).

### Recording metrics with predefined aggregation

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:
```
+------------------+
| MeterProvider | +-----------------+ +--------------+
| Meter A | Measurements... | | Metrics... | |
| Instrument X +-----------------> In-memory state +-------------> MetricReader |
| Instrument Y | | | | |
| Meter B | +-----------------+ +--------------+
| Instrument Z |
| ... | +-----------------+ +--------------+
| ... | Measurements... | | Metrics... | |
| ... +-----------------> In-memory state +-------------> MetricReader |
| ... | | | | |
| ... | +-----------------+ +--------------+
+------------------+
```

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

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.
[Instruments](metrics/api.md#instrument) are used to report `Measurement`s, and are identified
by a name, kind, description and a unit of values.

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

### 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 All @@ -297,6 +284,13 @@ from the backend.
See [Metrics Data Model Specification](metrics/data-model.md) for more
information.

#### Views

[Views](metrics/sdk.md#view) are configurations that specify how the data from an `Instrument` should be processed,
aggregated, and exported. They can be applied globally through the `MeterProvider` or more
specifically at the `Meter` level. A `View` allows the customization of metric data beyond the default
collection behavior, enabling specific aggregations, transformations, and filtering of metrics.

## Log Signal

### Data model
Expand Down

0 comments on commit 33dbeb6

Please sign in to comment.