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

Add Histogram description to DataModel Specification #1664

Merged
merged 22 commits into from
May 13, 2021
Merged
Show file tree
Hide file tree
Changes from 19 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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ release.
### Metrics

- Expand `Gauge` metric description in the data model ([#1661](https://github.com/open-telemetry/opentelemetry-specification/pull/1661))
- Expand `Histogram` metric description in the data model ([#1664](https://github.com/open-telemetry/opentelemetry-specification/pull/1664))

### Logs

Expand Down
47 changes: 46 additions & 1 deletion specification/metrics/datamodel.md
Original file line number Diff line number Diff line change
Expand Up @@ -324,7 +324,52 @@ user configuration.

### Histogram

Pending
[Histogram](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto#L225)
metric data points convey a population of recorded measurements in a compressed
format. A histogram bundles a set of events into divided populations with an
overall event count and aggregate sum for all events.

![Delta Histogram](img/model-delta-histogram.png)

Histograms consist of the following:

- An *Aggregation Temporality* of delta or cumulative.
- A set of data points, each containing:
- An independent set of Attribute name-value pairs.
- A time window (of `(start, end]`) time for which the Histogram was bundled.
- The time interval is inclusive of the end time.
- Time values are specified as nanoseconds since the UNIX Epoch
(00:00:00 UTC on 1 January 1970).
- A count (`count`) of the total population of points in the histogram.
- A sum (`sum`) of all the values in the histogram.
- (optional) A series of buckets with:
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- Explicit boundary values. These values denote the lower and upper bounds
for buckets and whether not a given observation would be recorded in this
bucket.
- A count of the number of observations that fell within this bucket.
- (optional) a set of examplars (see [Exemplars](#exemplars)).
jsuereth marked this conversation as resolved.
Show resolved Hide resolved

Like Sums, Histograms also define an aggregation temporality. The picture above
denotes Delta temporality where accumulated event counts are reset to zero after reporting
and a new aggregation occurs. Cumulative, on the other hand, continues to
aggregate events, resetting with the use of a new start time.

#### Exemplars

An exemplar is a recorded value that associates OpenTelemetry context to
a metric event within a Histogram. One use case is to allow users to link
Trace signals w/ Metrics.

Exemplars consist of:

- (optional) The trace associated with a recording (`trace_id`, `span_id`)
- The time of the observation (`time_unix_nano`)
- The recorded value (`value`)
- A set of filtered attributes (`filtered_attributes`) which provide
additional insight into the Context when the observation was made.

When an exemplar exists, its value already participates in `bucket_counts`,
`count` and `sum` reported by the histogram point.

### Summary (Legacy)

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.