// 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);
}
}
Codebase Browser
chromium