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 6 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 @@ -21,6 +21,7 @@ release.
- Expand description of Event Model and Instruments. ([#1614](https://github.com/open-telemetry/opentelemetry-specification/pull/1614))
- Flesh out metric identity and single-write principle. ([#1574](https://github.com/open-telemetry/opentelemetry-specification/pull/1574))
- Expand `Sum` metric description in the data model and delta-to-cumulative handling. ([#1618](https://github.com/open-telemetry/opentelemetry-specification/pull/1618))
- 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 @@ -300,7 +300,52 @@ Pending

### Histogram

Pending
[Histgram](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto#L225)
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
metric data points convey a population of recorded data points in a compressed
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
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.
- Times are specified in Value is UNIX Epoch time in nanoseconds since
`00:00:00 UTC on 1 January 1970`
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- 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 events are dropped after reporting
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
and a new aggregation occurs. Cumulative, on the other hand, continues to
aggregate events until a reset.
jsuereth marked this conversation as resolved.
Show resolved Hide resolved

#### Exemplars

An exemplar is a recorded value that associates OpenTelemetry context to
a metric event within a Histogram. It allows users to link Trace signals w/
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
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.