Add histogram_quantiles() API with enriched metadata support#69
Open
thinkingfish wants to merge 12 commits into
Open
Add histogram_quantiles() API with enriched metadata support#69thinkingfish wants to merge 12 commits into
thinkingfish wants to merge 12 commits into
Conversation
Adds HistogramSeries::quantiles() and Tsdb::quantiles() methods that return BTreeMap<Quantile, UntypedSeries> for keyed quantile lookups. Existing percentiles() API is left in place for backwards compatibility. Updates histogram dependency to path dep for development (1.1.0). https://claude.ai/code/session_01YQAY65y5zF3PdR2uuaypMj
Mark HistogramSeries::percentiles() and Tsdb::percentiles() as deprecated. Existing PromQL callers use #[allow(deprecated)] until they migrate to the new quantiles() API. https://claude.ai/code/session_01YQAY65y5zF3PdR2uuaypMj
Feature PRs use <version>-alpha.<revision> format only. Release version bumps are reserved for release PRs. https://claude.ai/code/session_01YQAY65y5zF3PdR2uuaypMj
Change the return type from BTreeMap<Quantile, UntypedSeries> to BTreeMap<u64, QuantilesResult> so each timestamp preserves the full QuantilesResult (quantile-to-bucket map, total_count, min, max) instead of flattening to just bucket end values. https://claude.ai/code/session_01YQAY65y5zF3PdR2uuaypMj
…metadata Add a new `histogram_quantiles()` PromQL function that uses the `QuantilesResult` API from histogram 1.1.0. Unlike the deprecated `histogram_percentiles()`, the new function enriches each MatrixSample with `total_counts`, `min_bucket_upperbounds`, and `max_bucket_upperbounds` per timestamp, enabling: - Hiding non-unique quantiles when sample count is low - Accurate percentage display in heatmaps using true total count - Authoritative min/max bucket values for Y-axis range decisions Also enriches `HistogramHeatmapData` and `HistogramHeatmapResult` with the same per-timestamp metadata, computed during the existing bucket iteration in `heatmap()`. Existing `histogram_percentiles()` and `histogram_quantile()` PromQL functions are preserved as-is for backward compatibility. https://claude.ai/code/session_01BKbdyjeu3VovVZafuXqD84
…ogram_quantiles Mark the internal handle_histogram_percentiles() method as deprecated to guide future callers toward histogram_quantiles() which provides enriched metadata via the QuantilesResult API. https://claude.ai/code/session_01BKbdyjeu3VovVZafuXqD84
Instead of embedding total_counts/min_bucket_upperbounds/max_bucket_upperbounds
as optional fields on MatrixSample, emit them as independent MatrixSample
entries labeled with a `stat` key. This keeps MatrixSample simple and allows
the metadata series to be independently queried, correlated, and analyzed.
histogram_quantiles() now returns:
- One series per quantile: {__name__: metric, quantile: "0.99"}
- total_count series: {__name__: metric, stat: "total_count"}
- min_bucket_upperbound: {__name__: metric, stat: "min_bucket_upperbound"}
- max_bucket_upperbound: {__name__: metric, stat: "max_bucket_upperbound"}
https://claude.ai/code/session_01BKbdyjeu3VovVZafuXqD84
Remove stat series (total_count, min/max_bucket_upperbound) from histogram_quantiles() response and add an optional `filtered` flag that suppresses quantile data points when the sample count is too low for that quantile to be meaningfully distinct from the next-lower one. https://claude.ai/code/session_01BKbdyjeu3VovVZafuXqD84
…ount Remove the `filtered` flag from histogram_quantiles() since it breaks PromQL compatibility. Add a new histogram_total_count(metric) query that returns per-timestamp sample counts as a time series, enabling the frontend to perform threshold-based quantile suppression client-side. https://claude.ai/code/session_01BKbdyjeu3VovVZafuXqD84
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a new
histogram_quantiles()query function that provides enriched histogram quantile results with per-timestamp metadata (total observation counts and min/max bucket upper bounds). This complements the existinghistogram_percentiles()function, which is now marked as deprecated.Key Changes
New
histogram_quantiles()query handler: Implements a modern quantile query API that leverages the newquantiles()method from the histogram crate (v1.1.0), returning structuredQuantilesResultobjects with full metadata.Enhanced data structures:
MatrixSample:total_counts,min_bucket_upperbounds,max_bucket_upperboundsHistogramHeatmapResultfor heatmap visualizationhistogram_quantiles()results and skipped during serialization whenNoneNew
HistogramSeries::quantiles()method: Computes quantile time series using theSampleQuantilestrait, returning aBTreeMap<u64, QuantilesResult>with per-timestamp quantile data and metadata.Deprecated
histogram_percentiles(): Marked as deprecated with guidance to usehistogram_quantiles()instead. All existing code paths updated to initialize new optional fields toNone.Heatmap metadata support: Enhanced heatmap generation to track and expose total counts and min/max bucket bounds per timestamp for improved visualization and percentage-based display.
Repository and dependency updates: Updated homepage/repository URLs to point to
iopsystems/metriken, upgraded histogram crate dependency to v1.1.0.Development guidelines: Added
CLAUDE.mddocumenting versioning conventions for feature PRs (alpha versioning) vs. release PRs.Implementation Details
The new
histogram_quantiles()function:histogram_quantiles([0.5, 0.9, 0.99], metric_name)quantiles()API for richer result dataMatrixSamplewith per-timestamp metadata for downstream consumershistogram_percentiles()functionalAll
MatrixSampleinstantiations throughout the query engine have been updated to explicitly set the new optional fields, ensuring consistent behavior across all query types.https://claude.ai/code/session_01BKbdyjeu3VovVZafuXqD84