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.

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

Clarify metric point #3906

Merged
merged 5 commits into from
Feb 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
9 changes: 7 additions & 2 deletions specification/metrics/data-model.md
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
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