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