{"record":{"id":"3ea020291693f693","repo":"apache/cassandra","slug":"unable-to-compute-ceiling-for-max-when-histogram-o","errorCode":null,"errorMessage":"Unable to compute ceiling for max when histogram overflowed","messagePattern":"Unable to compute ceiling for max when histogram overflowed","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/utils/EstimatedHistogram.java","lineNumber":262,"sourceCode":"\n    /**\n     * @return the ceil of mean histogram value (average of bucket offsets, weighted by count)\n     * @throws IllegalStateException if any values were greater than the largest bucket threshold\n     */\n    public long mean()\n    {\n        return (long) Math.ceil(rawMean());\n    }\n\n    /**\n     * @return the mean histogram value (average of bucket offsets, weighted by count)\n     * @throws IllegalStateException if any values were greater than the largest bucket threshold\n     */\n    public double rawMean()\n    {\n        int lastBucket = buckets.length() - 1;\n        if (buckets.get(lastBucket) > 0)\n            throw new IllegalStateException(\"Unable to compute ceiling for max when histogram overflowed\");\n\n        long elements = 0;\n        long sum = 0;\n        for (int i = 0; i < lastBucket; i++)\n        {\n            long bCount = buckets.get(i);\n            elements += bCount;\n            sum += bCount * bucketOffsets[i];\n        }\n\n        if (elements == 0)\n            return 0.0D;\n        return (double) sum / elements;\n    }\n\n    /**\n     * @return the total number of non-zero values\n     */","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/utils/EstimatedHistogram.java#L244-L280","documentation":"rawMean() computes the mean over non-overflow buckets. If any value exceeded the largest bucket threshold (last bucket count > 0), the true sum is unknown and the method throws IllegalStateException rather than return a wrong mean.","triggerScenarios":"Calling rawMean()/mean() on an EstimatedHistogram where at least one sample overflowed into the last bucket.","commonSituations":"Requesting mean latency/duration after pathological outliers (very long GC pauses, request durations above the histogram max), or using a histogram sized for one metric with another's data.","solutions":["Increase the histogram's bucket range at construction so realistic values fit below the max bucket","Check the overflow state before calling mean/rawMean and handle the overflow case explicitly","Aggregate or clamp extreme values at record time if they are not meaningful to measure"],"exampleFix":"// before\ndouble m = histogram.mean(); // throws when overflowed\n// after\nif (!histogram.isOverflowed()) {\n    double m = histogram.mean();\n} else {\n    // skip or alert on overflow\n}","handlingStrategy":"validation","validationCode":"Double safeMean(EstimatedHistogram h) {\n    return h.isOverflowed() ? null : h.mean();\n}","typeGuard":null,"tryCatchPattern":"try {\n    double m = histogram.mean();\n} catch (IllegalStateException e) {\n    // overflowed samples present: mean undefined\n}","preventionTips":["Check overflow before computing mean","Use bucket ranges that accommodate worst-case values (e.g. long GC pauses)","Clamp or route extreme samples to a separate histogram"],"tags":["histogram","metrics","overflow","java"],"backgroundTag":"internal-invariant-violation","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}