Conversation
|
I almost want to make the distribution streaming estimates private for now, or hide them behind a flag, because I think users probably shouldn't be using them for monitoring applications. For now, I'm just proposing a docs change, but we can also talk about hiding these somehow if useful. |
oximeter/oxql-types/src/point.rs
Outdated
| /// ranges. However, other statistical fields represent streaming | ||
| /// calculations: their value at a given point represents the cumulative | ||
| /// streaming estimate dating to the start time of that series. Streaming | ||
| /// estimates are also only available for the 0th point in a series and |
There was a problem hiding this comment.
This particular sentence seems more confusing than helpful, IMO. I'd probably cut it.
There was a problem hiding this comment.
Done. I couldn't think of a clear explanation that wasn't really long, so better to omit for now.
oximeter/oxql-types/src/point.rs
Outdated
| /// streaming estimate dating to the start time of that series. Streaming | ||
| /// estimates are also only available for the 0th point in a series and | ||
| /// after gaps in the series, since they can't be subtracted over time | ||
| /// points. Use histogram statistics rather than streaming statistics |
There was a problem hiding this comment.
This is the first time "histogram statistics" is used. Could we define it or use another phrase, like "statistics derived from bin counts"?
There was a problem hiding this comment.
I'm just changing this to "bin counts"
jmcarp
force-pushed
the
jmcarp/document-distribution-estimates
branch
2 times, most recently
from
0674a20 to
bfc529f
Compare
Distributions have two kinds of statistics: histogram bucket counts, which can be converted from cumulative values to deltas by subtraction; and streaming estimates (min, max, quantiles, etc.), which can't. Because streaming estimates can't be subtracted, they always reflect values since the start of the series's epoch, and can't be used to examine a specific time range (e.g., the last hour). Users should probably use histogram statistics and not streaming statistics for monitoring purposes. This patch updates the inline docs to clarify these differences and steer users toward histograms in most use cases.
jmcarp
force-pushed
the
jmcarp/document-distribution-estimates
branch
from
bfc529f to
fda073a
Compare
2 participants
Distributions have two kinds of statistics: histogram bucket counts, which can be converted from cumulative values to deltas by subtraction; and streaming estimates (min, max, quantiles, etc.), which can't. Because streaming estimates can't be subtracted, they always reflect values since the start of the series's epoch, and can't be used to examine a specific time range (e.g., the last hour). Users should probably use histogram statistics and not streaming statistics for monitoring purposes.
This patch updates the inline docs to clarify these differences and steer users toward histograms in most use cases.