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

Show file tree
Hide file tree
Changes from all commits
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
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,11 @@ release.

### Logs

- Remove implementation detail from Logs Bridge API.
([#3884](https://github.com/open-telemetry/opentelemetry-specification/pull/3884))
- Clarify that logs attributes are a superset of standard attributes.
([#3852](https://github.com/open-telemetry/opentelemetry-specification/pull/3852))

### Resource

### OpenTelemetry Protocol
Expand All @@ -30,6 +35,9 @@ release.

### Common

- Tighten stability requirements for well-known attribute values.
([#3879](https://github.com/open-telemetry/opentelemetry-specification/pull/3879))

### Supplementary Guidelines

## v1.30.0 (2024-02-15)
Expand Down
26 changes: 13 additions & 13 deletions spec-compliance-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,19 +199,19 @@ formats is required. Implementing more than one format is optional.
| The metrics Exporter `ForceFlush` can inform the caller whether it succeeded, failed or timed out. | | | + | + | - | | + | + | | + | + | |
| The metrics Exporter provides a `shutdown` function. | | + | + | + | - | | + | + | + | + | + | |
| The metrics Exporter `shutdown` function do not block indefinitely. | | + | + | + | - | | + | | | + | + | |
| The metrics SDK samples `Exemplar`s from measurements. | | | + | | - | | - | | | | - | |
| Exemplar sampling can be disabled. | | | - | | - | | - | | | | - | |
| The metrics SDK supports SDK-wide exemplar filter configuration | | | + | | - | | - | | | | - | |
| The metrics SDK supports `TraceBased` exemplar filter | | | + | | - | | - | | | | - | |
| The metrics SDK supports `AlwaysOn` exemplar filter | | | + | | - | | - | | | | - | |
| The metrics SDK supports `AlwaysOff` exemplar filter | | | + | | - | | - | | | | - | |
| Exemplars retain any attributes available in the measurement that are not preserved by aggregation or view configuration. | | | + | | - | | - | | | | - | |
| Exemplars contain the associated trace id and span id of the active span in the Context when the measurement was taken. | | | + | | - | | - | | | | - | |
| Exemplars contain the timestamp when the measurement was taken. | | | + | | - | | - | | | | - | |
| The metrics SDK provides an `ExemplarReservoir` interface or extension point. | X | | - | | - | | - | + | | | - | |
| An `ExemplarReservoir` has an `offer` method with access to the measurement value, attributes, `Context` and timestamp. | X | | - | | - | | - | + | | | - | |
| The metrics SDK provides a `SimpleFixedSizeExemplarReservoir` that is used by default for all aggregations except `ExplicitBucketHistogram`. | | | + | | - | | - | + | | | - | |
| The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation. | | | + | | - | | - | | | | - | |
| The metrics SDK samples `Exemplar`s from measurements. | | | + | | - | | + | | | | - | |
| Exemplar sampling can be disabled. | | | - | | - | | + | | | | - | |
| The metrics SDK supports SDK-wide exemplar filter configuration | | | + | | - | | + | | | | - | |
| The metrics SDK supports `TraceBased` exemplar filter | | | + | | - | | + | | | | - | |
| The metrics SDK supports `AlwaysOn` exemplar filter | | | + | | - | | + | | | | - | |
| The metrics SDK supports `AlwaysOff` exemplar filter | | | + | | - | | + | | | | - | |
| Exemplars retain any attributes available in the measurement that are not preserved by aggregation or view configuration. | | | + | | - | | + | | | | - | |
| Exemplars contain the associated trace id and span id of the active span in the Context when the measurement was taken. | | | + | | - | | + | | | | - | |
| Exemplars contain the timestamp when the measurement was taken. | | | + | | - | | + | | | | - | |
| The metrics SDK provides an `ExemplarReservoir` interface or extension point. | X | | - | | - | | + | + | | | - | |
| An `ExemplarReservoir` has an `offer` method with access to the measurement value, attributes, `Context` and timestamp. | X | | - | | - | | + | + | | | - | |
| The metrics SDK provides a `SimpleFixedSizeExemplarReservoir` that is used by default for all aggregations except `ExplicitBucketHistogram`. | | | + | | - | | + | + | | | - | |
| The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation. | | | + | | - | | + | | | | - | |
| A metric Producer accepts an optional metric Filter | | | | | | | - | | | | | |
| The metric Reader implementation supports registering metric Filter and passing them its registered metric Producers | | | | | | | - | | | | | |
| The metric SDK's metric Producer implementations uses the metric Filter | | | | | | | - | | | | | |
Expand Down
3 changes: 0 additions & 3 deletions specification/logs/bridge-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,6 @@ graph TD

`Logger`s can be accessed with a `LoggerProvider`.

In implementations of the API, the `LoggerProvider` is expected to be the stateful
object that holds any configuration.

Normally, the `LoggerProvider` is expected to be accessed from a central place.
Thus, the API SHOULD provide a way to set/register and access a global default
`LoggerProvider`.
Expand Down
8 changes: 5 additions & 3 deletions specification/logs/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,13 +442,15 @@ is optional.

### Field: `Attributes`

Type: `map<string, any>`.
Type: [`map<string, any>`](#type-mapstring-any).

Description: Additional information about the specific event occurrence. Unlike
the `Resource` field, which is fixed for a particular source, `Attributes` can
vary for each occurrence of the event coming from the same source. Can contain
information about the request context (other than TraceId/SpanId). SHOULD follow
OpenTelemetry [semantic conventions for attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md).
information about the request context (other than [Trace Context Fields](#trace-context-fields)).
The log attribute model MUST support [`any` type](#type-any),
a superset of [standard Attribute](../common/README.md#attribute),
to preserve the semantics of structured attributes emitted by the applications.
This field is optional.

#### Errors and Exceptions
Expand Down
9 changes: 7 additions & 2 deletions specification/metrics/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ aliases: [/docs/reference/specification/metrics/datamodel]
+ [OpenTelemetry Protocol data model: Producer recommendations](#opentelemetry-protocol-data-model-producer-recommendations)
+ [OpenTelemetry Protocol data model: Consumer recommendations](#opentelemetry-protocol-data-model-consumer-recommendations)
+ [Point kinds](#point-kinds)
- [Metric points](#metric-points)
- [Metric Points](#metric-points)
* [Sums](#sums)
* [Gauge](#gauge)
* [Histogram](#histogram)
Expand Down Expand Up @@ -381,10 +381,15 @@ designed for compatibility with existing metric formats.

- [Summary](#summary-legacy)

## Metric points
## Metric Points

**Status**: [Stable](../document-status.md)

Metric points are the basic building blocks of metrics. Depending on the [point
kind](#point-kinds), a metric point may have different fields. The following
sections describe the fields for each point kind and how these points form
metrics.

### Sums

[Sum](https://github.com/open-telemetry/opentelemetry-proto/blob/v0.9.0/opentelemetry/proto/metrics/v1/metrics.proto#L230)s
Expand Down
27 changes: 14 additions & 13 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -733,8 +733,9 @@ of metrics across successive collections.

SDKs SHOULD support being configured with a cardinality limit. The number of
unique combinations of attributes is called cardinality. For a given metric, the
cardinality limit is a hard limit on the number of metric points that can be
collected during a collection cycle.
cardinality limit is a hard limit on the number of [Metric
Points](./data-model.md#metric-points) that can be collected during a collection
cycle.

#### Configuration

Expand Down Expand Up @@ -1383,12 +1384,12 @@ A Push Metric Exporter MUST support the following functions:

##### Export(batch)

Exports a batch of [Metric points](./data-model.md#metric-points). Protocol
Exports a batch of [Metric Points](./data-model.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 point`.
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.
Expand All @@ -1403,10 +1404,10 @@ are being sent to.

**Parameters:**

`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:
`batch` - a batch of [Metric Points](./data-model.md#metric-points). 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
+--------+ +--------+ +--------+
Expand All @@ -1422,7 +1423,7 @@ Batch: | Metric | | Metric | ... | Metric |
+--> timestamps, attributes, value (or buckets), exemplars, ...
```

Refer to the [Metric points](./data-model.md#metric-points) section from the
Refer to the [Metric Points](./data-model.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
Expand Down Expand Up @@ -1562,12 +1563,12 @@ A `MetricProducer` MUST support the following functions:
#### Produce batch

`Produce` provides metrics from the MetricProducer to the caller. `Produce`
MUST return a batch of [Metric points](./data-model.md#metric-points), filtered by the optional
MUST return a batch of [Metric Points](./data-model.md#metric-points), filtered by the optional
`metricFilter` parameter. Implementation SHOULD use the filter as early as
possible to gain as much performance gain possible (memory allocation,
internal metric fetching, etc).

If the batch of [Metric points](./data-model.md#metric-points) includes
If the batch of [Metric Points](./data-model.md#metric-points) includes
resource information, `Produce` SHOULD require a resource as a parameter.
`Produce` does not have any other required parameters, however, [OpenTelemetry
SDK](../overview.md#sdk) authors MAY choose to add required or optional
Expand All @@ -1578,7 +1579,7 @@ failed or timed out. When the `Produce` operation fails, the `MetricProducer`
MAY return successfully collected results and a failed reasons list to the
caller.

If a batch of [Metric points](./data-model.md#metric-points) can include
If a batch of [Metric Points](./data-model.md#metric-points) can include
[`InstrumentationScope`](../glossary.md#instrumentation-scope) information,
`Produce` SHOULD include a single InstrumentationScope which identifies the
`MetricProducer`.
Expand All @@ -1593,7 +1594,7 @@ If a batch of [Metric points](./data-model.md#metric-points) can include

`MetricFilter` defines the interface which enables the [MetricReader](#metricreader)'s
registered [MetricProducers](#metricproducer) or the SDK's [MetricProducer](#metricproducer) to filter aggregated data points
([Metric points](./data-model.md#metric-points)) inside its `Produce` operation.
([Metric Points](./data-model.md#metric-points)) inside its `Produce` operation.
The filtering is done at the [MetricProducer](#metricproducer) for performance reasons.

The `MetricFilter` allows filtering an entire metric stream - dropping or allowing all its attribute sets -
Expand Down
Loading