1 // Copyright 2019 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 package org.chromium.base.metrics; 6 7 import com.google.errorprone.annotations.DoNotMock; 8 9 import org.chromium.base.Callback; 10 11 import java.util.List; 12 13 /** Common interface for code recording UMA metrics. */ 14 @DoNotMock("Use HistogramWatcher for histograms or UserActionTester for user actions instead.") 15 public interface UmaRecorder { 16 /** Records a single sample of a boolean histogram. */ recordBooleanHistogram(String name, boolean sample)17 void recordBooleanHistogram(String name, boolean sample); 18 19 /** 20 * Records a single sample of a histogram with exponentially scaled buckets. See 21 * {@link 22 * https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md#count-histograms} 23 * <p> 24 * This is the default histogram type used by "counts", "times" and "memory" histograms in 25 * {@code base/metrics/histogram_functions.h} 26 * 27 * @param min the smallest value recorded in the first bucket; should be greater than zero. 28 * @param max the smallest value recorded in the overflow bucket. 29 * @param numBuckets number of histogram buckets: Two buckets are used for underflow and 30 * overflow, and the remaining buckets cover the range {@code [min, max)}; {@code 31 * numBuckets} should be {@code 100} or less. 32 */ recordExponentialHistogram(String name, int sample, int min, int max, int numBuckets)33 void recordExponentialHistogram(String name, int sample, int min, int max, int numBuckets); 34 35 /** 36 * Records a single sample of a histogram with evenly spaced buckets. See 37 * {@link 38 * https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md#percentage-or-ratio-histograms} 39 * <p> 40 * This histogram type is best suited for recording enums, percentages and ratios. 41 * 42 * @param min the smallest value recorded in the first bucket; should be equal to one, but will 43 * work with values greater than zero. 44 * @param max the smallest value recorded in the overflow bucket. 45 * @param numBuckets number of histogram buckets: Two buckets are used for underflow and 46 * overflow, and the remaining buckets evenly cover the range {@code [min, max)}; {@code 47 * numBuckets} should be {@code 100} or less. 48 */ recordLinearHistogram(String name, int sample, int min, int max, int numBuckets)49 void recordLinearHistogram(String name, int sample, int min, int max, int numBuckets); 50 51 /** 52 * Records a single sample of a sparse histogram. See 53 * {@link 54 * https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md#when-to-use-sparse-histograms} 55 */ recordSparseHistogram(String name, int sample)56 void recordSparseHistogram(String name, int sample); 57 58 /** 59 * Records a user action. Action names must be documented in {@code actions.xml}. See {@link 60 * https://source.chromium.org/chromium/chromium/src/+/main:tools/metrics/actions/README.md} 61 * 62 * @param name Name of the user action. 63 * @param elapsedRealtimeMillis Value of {@link android.os.SystemClock.elapsedRealtime()} when 64 * the action was observed. 65 */ recordUserAction(String name, long elapsedRealtimeMillis)66 void recordUserAction(String name, long elapsedRealtimeMillis); 67 68 /** 69 * Returns the number of samples recorded in the given bucket of the given histogram. 70 * Does not reset between batched tests. Different values may fall in the same bucket. Use 71 * HistogramWatcher instead. 72 * 73 * @param name name of the histogram to look up 74 * @param sample the bucket containing this sample value will be looked up 75 */ getHistogramValueCountForTesting(String name, int sample)76 int getHistogramValueCountForTesting(String name, int sample); 77 78 /** 79 * Returns the number of samples recorded for the given histogram. 80 * Does not reset between batched tests. Use HistogramWatcher instead. 81 * 82 * @param name name of the histogram to look up 83 */ getHistogramTotalCountForTesting(String name)84 int getHistogramTotalCountForTesting(String name); 85 86 /** 87 * Returns the buckets with the samples recorded for the given histogram. 88 * Does not reset between batched tests. Use HistogramWatcher instead. 89 * 90 * @param name name of the histogram to look up 91 */ getHistogramSamplesForTesting(String name)92 List<HistogramBucket> getHistogramSamplesForTesting(String name); 93 94 /** 95 * Adds a testing callback to be notified on all actions recorded through 96 * {@link RecordUserAction#record(String)}. 97 * 98 * @param callback The callback to be added. 99 */ addUserActionCallbackForTesting(Callback<String> callback)100 void addUserActionCallbackForTesting(Callback<String> callback); 101 102 /** 103 * Removes a previously added testing user action callback. 104 * 105 * @param callback The callback to be removed. 106 */ removeUserActionCallbackForTesting(Callback<String> callback)107 void removeUserActionCallbackForTesting(Callback<String> callback); 108 } 109