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 ExponentialHistogram to Metrics data model #1935

Merged
merged 26 commits into from
Oct 7, 2021
Merged
Changes from 1 commit
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
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
76 changes: 76 additions & 0 deletions specification/metrics/datamodel.md
Original file line number Diff line number Diff line change
Expand Up @@ -398,6 +398,82 @@ denotes Delta temporality where accumulated event counts are reset to zero after
and a new aggregation occurs. Cumulative, on the other hand, continues to
aggregate events, resetting with the use of a new start time.

### ExponentialHistogram
jmacd marked this conversation as resolved.
Show resolved Hide resolved

[ExponentialHistogram](TBD_after_PR322_merges) data points are an
alternate representation, like the [Histogram](#histogram) that convey
a population of recorded measurements in a compressed format.
ExponentialHistogram compresses bucket boundaries using an exponential
formula, making it suitable for conveying high-resolution histogram
data with a large number of buckets.

Statements about `Histogram` that refer to aggregation temporality,
attributes, timestamps, as well as the `sum`, `count`, `exemplars`
fields are identical for `ExponentialHistogram`.

The resolution of the ExponentialHistogram is characterized by a
parameter known as `scale`, with larger values of `scale` offering
greater precision. Bucket boundaries of the ExponentialHistogram are
located at integer powers of the `base`, where:

```
base = 2**(2**(-scale))
```

The symbol `**` in these formulas represents exponentiation, thus
`2**x` is read "Two to the power of X", typically computed by an
expression like `math.Pow(2.0, x)`. Calculated `base` values for
selected scales are shown below:

| Scale | Base | Expression |
| -- | -- | -- |
| 10 | 1.000677130693066 | 2**(1/1024) |
| 9 | 1.001354719892108 | 2**(1/512) |
| 8 | 1.002711275050203 | 2**(1/256) |
| 7 | 1.005429901112803 | 2**(1/128) |
| 6 | 1.010889286051700 | 2**(1/64) |
| 5 | 1.021897148654117 | 2**(1/32) |
| 4 | 1.044273782427414 | 2**(1/16) |
| 3 | 1.090507732665258 | 2**(1/8) |
| 2 | 1.189207115002721 | 2**(1/4) |
| 1 | 1.414213562373095 | 2**(1/2) |
| 0 | 2 | 2**1 |
| -1 | 4 | 2**2 |
| -2 | 16 | 2**4 |
| -3 | 256 | 2**8 |
| -4 | 65536 | 2**16 |

The ExponentialHistogram bucket identified by `index`, a signed
integer, represents values in the population that are greater than or
equal to `base**index` and less than `base**(index+1)`.
jmacd marked this conversation as resolved.
Show resolved Hide resolved

The positive and negative ranges of the histogram are expressed
separately. Negative values are mapped by their absolute value
into the negative range using the same scale as the positive range.

Each range of the ExponentialHistogram data point uses a dense
representation of the buckets, where a range of buckets is expressed
as a single `offset` value, a signed integer, and an array of count
values, where array element `i` represents the bucket count for bucket
index `offset+i`.

For a given range, positive or negative:

- The absolute value 1.0 has bucket index `0`
- Bucket index `0` counts measurements greater than or equal to 1.0 and less than `base`
- Negative indexes correspond with absolute values less than 1.0.

The ExponentialHistogram contains a special `zero_count` field
containing is the count of values that are either exactly zero or
within the region considered zero by the instrumentation at the
tolerated degree of precision. This bucket stores values that cannot
be expressed using the standard exponential formula as well as values
that have been rounded to zero.

#### Producers and consumer requirements

TODO: Work-In-Progress.

### Summary (Legacy)

[Summary](https://github.com/open-telemetry/opentelemetry-proto/blob/v0.9.0/opentelemetry/proto/metrics/v1/metrics.proto#L268)
Expand Down