Skip to content

Commit

Permalink
Clarify time window length in docs
Browse files Browse the repository at this point in the history
Users would have had to read the JavaDocs or look at the implementation to understand that the window length is the `expiry` * `bufferLength`. Updated the docs to explicitly call that out.

Closes gh-4625
  • Loading branch information
shakuzen committed Jan 30, 2024
1 parent d0c6753 commit b771359
Show file tree
Hide file tree
Showing 2 changed files with 4 additions and 2 deletions.
3 changes: 2 additions & 1 deletion docs/modules/ROOT/pages/concepts/distribution-summaries.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ DistributionSummary summary = DistributionSummary
NOTE: The maximum (which is named `max`) for basic `DistributionSummary` implementations, such as `CumulativeDistributionSummary` and `StepDistributionSummary`, is a time window maximum (`TimeWindowMax`).
It means that its value is the maximum value during a time window.
If no new values are recorded for the time window length, the maximum is reset to 0 as a new time window starts.
Time window size is the step size of the meter registry, unless expiry in `DistributionStatisticConfig` is explicitly set to another value.
The time window size until values are fully expired is the `expiry` multiplied by the `bufferLength` in `DistributionStatisticConfig`.
`expiry` defaults to the step size of the meter registry unless is explicitly set to a different value, and `bufferLength` defaults to `3`.
A time window max is used to capture the maximum latency in a subsequent interval after heavy resource pressure triggers the latency and prevents metrics from being published.
Percentiles are also time window percentiles (`TimeWindowPercentileHistogram`).

Expand Down
3 changes: 2 additions & 1 deletion docs/modules/ROOT/pages/concepts/timers.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ Timer timer = Timer
NOTE: The maximum statistical value for basic `Timer` implementations, such as `CumulativeTimer` and `StepTimer`, is a time window maximum (`TimeWindowMax`).
It means that its value is the maximum value during a time window.
If no new values are recorded for the time window length, the max is reset to 0 as a new time window starts.
Time window size is the step size of the meter registry unless expiry in `DistributionStatisticConfig` is explicitly set to a different value.
The time window size until values are fully expired is the `expiry` multiplied by the `bufferLength` in `DistributionStatisticConfig`.
`expiry` defaults to the step size of the meter registry unless is explicitly set to a different value, and `bufferLength` defaults to `3`.
A time window maximum is used to capture maximum latency in a subsequent interval after heavy resource pressure triggers the latency and prevents metrics from being published.
Percentiles are also time window percentiles (`TimeWindowPercentileHistogram`). Histogram buckets usually behave like counters so depending on the backend, they can be reported as cumulative values (for example in the case of Prometheus) or as a rate at which a counter increments over the push interval.

Expand Down

0 comments on commit b771359

Please sign in to comment.