xref: /external/cronet/base/android/java/src/org/chromium/base/metrics/RecordHistogram.java

// Copyright 2014 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package org.chromium.base.metrics;

import android.text.format.DateUtils;

import java.util.List;

/**
 * Java API for recording UMA histograms.
 * */
public class RecordHistogram {
    /**
     * Records a sample in a boolean UMA histogram of the given name. Boolean histogram has two
     * buckets, corresponding to success (true) and failure (false). This is the Java equivalent of
     * the UMA_HISTOGRAM_BOOLEAN C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, either true or false
     */
    public static void recordBooleanHistogram(String name, boolean sample) {
        UmaRecorderHolder.get().recordBooleanHistogram(name, sample);
    }

    /**
     * Records a sample in an enumerated histogram of the given name and boundary. Note that
     * {@code max} identifies the histogram - it should be the same at every invocation. This is the
     * Java equivalent of the UMA_HISTOGRAM_ENUMERATION C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, at least 0 and at most {@code max-1}
     * @param max upper bound for legal sample values - all sample values have to be strictly
     *            lower than {@code max}
     */
    public static void recordEnumeratedHistogram(String name, int sample, int max) {
        recordExactLinearHistogram(name, sample, max);
    }

    /**
     * Records a sample in a count histogram. This is the Java equivalent of the
     * UMA_HISTOGRAM_COUNTS_1M C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, at least 1 and at most 999999
     */
    public static void recordCount1MHistogram(String name, int sample) {
        UmaRecorderHolder.get().recordExponentialHistogram(name, sample, 1, 1_000_000, 50);
    }

    /**
     * Records a sample in a count histogram. This is the Java equivalent of the
     * UMA_HISTOGRAM_COUNTS_100 C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, at least 1 and at most 99
     */
    public static void recordCount100Histogram(String name, int sample) {
        UmaRecorderHolder.get().recordExponentialHistogram(name, sample, 1, 100, 50);
    }

    /**
     * Records a sample in a count histogram. This is the Java equivalent of the
     * UMA_HISTOGRAM_COUNTS_1000 C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, at least 1 and at most 999
     */
    public static void recordCount1000Histogram(String name, int sample) {
        UmaRecorderHolder.get().recordExponentialHistogram(name, sample, 1, 1_000, 50);
    }

    /**
     * Records a sample in a count histogram. This is the Java equivalent of the
     * UMA_HISTOGRAM_COUNTS_100000 C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, at least 1 and at most 99999
     */
    public static void recordCount100000Histogram(String name, int sample) {
        UmaRecorderHolder.get().recordExponentialHistogram(name, sample, 1, 100_000, 50);
    }

    /**
     * Records a sample in a count histogram. This is the Java equivalent of the
     * UMA_HISTOGRAM_CUSTOM_COUNTS C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, expected to fall in range {@code [min, max)}
     * @param min the smallest expected sample value; at least 1
     * @param max the smallest sample value that will be recorded in overflow bucket
     * @param numBuckets the number of buckets including underflow ({@code [0, min)}) and overflow
     *                   ({@code [max, inf)}) buckets; at most 100
     */
    public static void recordCustomCountHistogram(
            String name, int sample, int min, int max, int numBuckets) {
        UmaRecorderHolder.get().recordExponentialHistogram(name, sample, min, max, numBuckets);
    }

    /**
     * Records a sample in a linear histogram. This is the Java equivalent for using
     * {@code base::LinearHistogram}.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, expected to fall in range {@code [min, max)}
     * @param min the smallest expected sample value; at least 1
     * @param max the smallest sample value that will be recorded in overflow bucket
     * @param numBuckets the number of buckets including underflow ({@code [0, min)}) and overflow
     *                   ({@code [max, inf)}) buckets; at most 100
     */
    public static void recordLinearCountHistogram(
            String name, int sample, int min, int max, int numBuckets) {
        UmaRecorderHolder.get().recordLinearHistogram(name, sample, min, max, numBuckets);
    }

    /**
     * Records a sample in a percentage histogram. This is the Java equivalent of the
     * UMA_HISTOGRAM_PERCENTAGE C++ macro.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, at least 0 and at most 100
     */
    public static void recordPercentageHistogram(String name, int sample) {
        recordExactLinearHistogram(name, sample, 101);
    }

    /**
     * Records a sparse histogram. This is the Java equivalent of {@code base::UmaHistogramSparse}.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded: All values of {@code sample} are valid, including
     *               negative values. Keep the number of distinct values across all users
     *               {@code <= 100} ideally, definitely {@code <= 1000}.
     */
    public static void recordSparseHistogram(String name, int sample) {
        UmaRecorderHolder.get().recordSparseHistogram(name, sample);
    }

    /**
     * Records a sample in a histogram of times. Useful for recording short durations. This is the
     * Java equivalent of the UMA_HISTOGRAM_TIMES C++ macro.
     * <p>
     * Note that histogram samples will always be converted to milliseconds when logged.
     *
     * @param name name of the histogram
     * @param durationMs duration to be recorded in milliseconds
     */
    public static void recordTimesHistogram(String name, long durationMs) {
        recordCustomTimesHistogramMilliseconds(
                name, durationMs, 1, DateUtils.SECOND_IN_MILLIS * 10, 50);
    }

    /**
     * Records a sample in a histogram of times. Useful for recording medium durations. This is the
     * Java equivalent of the UMA_HISTOGRAM_MEDIUM_TIMES C++ macro.
     * <p>
     * Note that histogram samples will always be converted to milliseconds when logged.
     *
     * @param name name of the histogram
     * @param durationMs duration to be recorded in milliseconds
     */
    public static void recordMediumTimesHistogram(String name, long durationMs) {
        recordCustomTimesHistogramMilliseconds(
                name, durationMs, 10, DateUtils.MINUTE_IN_MILLIS * 3, 50);
    }

    /**
     * Records a sample in a histogram of times. Useful for recording long durations. This is the
     * Java equivalent of the UMA_HISTOGRAM_LONG_TIMES C++ macro.
     * <p>
     * Note that histogram samples will always be converted to milliseconds when logged.
     *
     * @param name name of the histogram
     * @param durationMs duration to be recorded in milliseconds
     */
    public static void recordLongTimesHistogram(String name, long durationMs) {
        recordCustomTimesHistogramMilliseconds(name, durationMs, 1, DateUtils.HOUR_IN_MILLIS, 50);
    }

    /**
     * Records a sample in a histogram of times. Useful for recording long durations. This is the
     * Java equivalent of the UMA_HISTOGRAM_LONG_TIMES_100 C++ macro.
     * <p>
     * Note that histogram samples will always be converted to milliseconds when logged.
     *
     * @param name name of the histogram
     * @param durationMs duration to be recorded in milliseconds
     */
    public static void recordLongTimesHistogram100(String name, long durationMs) {
        recordCustomTimesHistogramMilliseconds(name, durationMs, 1, DateUtils.HOUR_IN_MILLIS, 100);
    }

    /**
     * Records a sample in a histogram of times with custom buckets. This is the Java equivalent of
     * the UMA_HISTOGRAM_CUSTOM_TIMES C++ macro.
     * <p>
     * Note that histogram samples will always be converted to milliseconds when logged.
     *
     * @param name name of the histogram
     * @param durationMs duration to be recorded in milliseconds; expected to fall in range
     *                   {@code [min, max)}
     * @param min the smallest expected sample value; at least 1
     * @param max the smallest sample value that will be recorded in overflow bucket
     * @param numBuckets the number of buckets including underflow ({@code [0, min)}) and overflow
     *                   ({@code [max, inf)}) buckets; at most 100
     */
    public static void recordCustomTimesHistogram(
            String name, long durationMs, long min, long max, int numBuckets) {
        recordCustomTimesHistogramMilliseconds(name, durationMs, min, max, numBuckets);
    }

    /**
     * Records a sample in a histogram of sizes in KB. This is the Java equivalent of the
     * UMA_HISTOGRAM_MEMORY_KB C++ macro.
     * <p>
     * Good for sizes up to about 500MB.
     *
     * @param name name of the histogram
     * @param sizeInkB Sample to record in KB
     */
    public static void recordMemoryKBHistogram(String name, int sizeInKB) {
        UmaRecorderHolder.get().recordExponentialHistogram(name, sizeInKB, 1000, 500000, 50);
    }

    /**
     * Records a sample in a histogram of sizes in MB. This is the Java equivalent of the
     * UMA_HISTOGRAM_MEMORY_MEDIUM_MB C++ macro.
     * <p>
     * Good for sizes up to about 4000MB.
     *
     * @param name name of the histogram
     * @param sizeInMB Sample to record in MB
     */
    public static void recordMemoryMediumMBHistogram(String name, int sizeInMB) {
        UmaRecorderHolder.get().recordExponentialHistogram(name, sizeInMB, 1, 4000, 100);
    }

    /**
     * Records a sample in a linear histogram where each bucket in range {@code [0, max)} counts
     * exactly a single value.
     *
     * @param name name of the histogram
     * @param sample sample to be recorded, expected to fall in range {@code [0, max)}
     * @param max the smallest value counted in the overflow bucket, shouldn't be larger than 100
     */
    public static void recordExactLinearHistogram(String name, int sample, int max) {
        // Range [0, 1) is counted in the underflow bucket. The first "real" bucket starts at 1.
        final int min = 1;
        // One extra is added for the overflow bucket.
        final int numBuckets = max + 1;
        UmaRecorderHolder.get().recordLinearHistogram(name, sample, min, max, numBuckets);
    }

    private static int clampToInt(long value) {
        if (value > Integer.MAX_VALUE) return Integer.MAX_VALUE;
        // Note: Clamping to MIN_VALUE rather than 0, to let base/ histograms code do its own
        // handling of negative values in the future.
        if (value < Integer.MIN_VALUE) return Integer.MIN_VALUE;
        return (int) value;
    }

    private static void recordCustomTimesHistogramMilliseconds(
            String name, long duration, long min, long max, int numBuckets) {
        UmaRecorderHolder.get()
                .recordExponentialHistogram(
                        name, clampToInt(duration), clampToInt(min), clampToInt(max), numBuckets);
    }

    /**
     * Returns the number of samples recorded in the given bucket of the given histogram.
     *
     * @deprecated Raw counts are easy to misuse. Does not reset between batched tests. Use
     * {@link org.chromium.base.test.util.HistogramWatcher} instead.
     *
     * @param name name of the histogram to look up
     * @param sample the bucket containing this sample value will be looked up
     */
    @Deprecated
    public static int getHistogramValueCountForTesting(String name, int sample) {
        return UmaRecorderHolder.get().getHistogramValueCountForTesting(name, sample);
    }

    /**
     * Returns the number of samples recorded for the given histogram.
     *
     * @deprecated Raw counts are easy to misuse. Does not reset between batched tests. Use
     * {@link org.chromium.base.test.util.HistogramWatcher} instead.
     *
     * @param name name of the histogram to look up
     */
    @Deprecated
    public static int getHistogramTotalCountForTesting(String name) {
        return UmaRecorderHolder.get().getHistogramTotalCountForTesting(name);
    }

    /**
     * Returns the buckets of samples recorded for the given histogram.
     *
     * Use {@link org.chromium.base.test.util.HistogramWatcher} instead of using this directly.
     *
     * @param name name of the histogram to look up
     */
    public static List<HistogramBucket> getHistogramSamplesForTesting(String name) {
        return UmaRecorderHolder.get().getHistogramSamplesForTesting(name);
    }
}