Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 1 | Copyright (c) 2010 The Chromium OS Authors. All rights reserved. |
| 2 | Use of this source code is governed by a BSD-style license that can be |
| 3 | found in the LICENSE file. |
Darin Petkov | 65b0146 | 2010-04-14 13:32:20 -0700 | [diff] [blame] | 4 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 5 | The Chrome OS "metrics" package contains utilities for client-side user metric |
| 6 | collection. The collected data is sent to Chrome for transport to the UMA |
| 7 | server. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 8 | |
| 9 | |
| 10 | ================================================================================ |
| 11 | The Metrics Library: libmetrics |
| 12 | ================================================================================ |
| 13 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 14 | libmetrics is a small library that implements the basic C and C++ API for |
| 15 | metrics collection. All metrics collection is funneled through this library. The |
| 16 | easiest and recommended way for a client-side module to collect user metrics is |
| 17 | to link libmetrics and use its APIs to send metrics to Chrome for transport to |
| 18 | UMA. In order to use the library in a module, you need to do the following: |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 19 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 20 | - Add a dependence (DEPEND and RDEPEND) on chromeos-base/metrics to the module's |
| 21 | ebuild. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 22 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 23 | - Link the module with libmetrics (for example, by passing -lmetrics to the |
| 24 | module's link command). Both libmetrics.so and libmetrics.a are built and |
| 25 | installed under $SYSROOT/usr/lib/. Note that by default -lmetrics will link |
| 26 | against libmetrics.so, which is preferred. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 27 | |
| 28 | - To access the metrics library API in the module, include the |
Darin Petkov | c80dd92 | 2010-05-14 09:12:36 -0700 | [diff] [blame] | 29 | <metrics/metrics_library.h> header file. The file is installed in |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 30 | $SYSROOT/usr/include/ when the metrics library is built and installed. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 31 | |
Darin Petkov | fc91b42 | 2010-05-12 13:05:45 -0700 | [diff] [blame] | 32 | - The API includes two methods: |
| 33 | |
| 34 | bool MetricsLibrary::SendToUMA(const std::string& name, int sample, |
| 35 | int min, int max, int nbuckets) |
| 36 | sends a sample for a regular (exponential) histogram. |
| 37 | |
| 38 | bool MetricsLibrary::SendEnumToUMA(const std::string& name, int sample, |
| 39 | int max) |
| 40 | sends a sample for an enumeration (linear) histogram. |
| 41 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 42 | Before using these methods, a MetricsLibrary object needs to be constructed |
| 43 | and initialized through its Init method. See the complete API documentation in |
| 44 | metrics_library.h under src/platform/metrics/. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 45 | |
Darin Petkov | 32e1df9 | 2010-06-17 17:05:06 -0700 | [diff] [blame] | 46 | For more information on the C API see c_metrics_library.h. |
| 47 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 48 | - Samples are sent to Chrome only if the "/home/chronos/Consent To Send Stats" |
| 49 | file exists (see the AreMetricsEnabled API method). Normally, this file is |
| 50 | created when the user opts into metrics collection. |
| 51 | |
| 52 | - On the target platform, shortly after the sample is sent, it should be visible |
| 53 | in Chrome through "about:histograms". |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 54 | |
| 55 | |
| 56 | ================================================================================ |
| 57 | Histogram Naming Convention |
| 58 | ================================================================================ |
| 59 | |
| 60 | Use TrackerArea.MetricName. For example: |
| 61 | |
| 62 | Logging.CrashCounter |
| 63 | Network.TimeToDrop |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 64 | |
| 65 | |
| 66 | ================================================================================ |
| 67 | Server Side |
| 68 | ================================================================================ |
| 69 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 70 | If the histogram data is visible in about:histograms, it will be sent by an |
| 71 | official Chrome build to UMA, assuming the user has opted into metrics |
| 72 | collection. To make the histogram visible on "chromedashboard", the histogram |
| 73 | description XML file needs to be updated (steps 2 and 3 after following the |
| 74 | "Details on how to add your own histograms" link under the Histograms tab). |
| 75 | Include the string "Chrome OS" in the histogram description so that it's easier |
| 76 | to distinguish Chrome OS specific metrics from general Chrome histograms. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 77 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 78 | The UMA server logs and keeps the collected field data even if the metric's name |
| 79 | is not added to the histogram XML. However, the dashboard histogram for that |
| 80 | metric will show field data as of the histogram XML update date; it will not |
| 81 | include data for older dates. If past data needs to be displayed, manual |
| 82 | server-side intervention is required. In other words, one should assume that |
| 83 | field data collection starts only after the histogram XML has been updated. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 84 | |
| 85 | |
| 86 | ================================================================================ |
| 87 | The Metrics Client: metrics_client |
| 88 | ================================================================================ |
| 89 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 90 | metrics_client is a simple shell command-line utility for sending histogram |
| 91 | samples. It's installed under /usr/bin on the target platform and uses |
| 92 | libmetrics to send the data to Chrome. The utility is useful for generating |
| 93 | metrics from shell scripts. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 94 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 95 | For usage information and command-line options, run "metrics_client" on the |
| 96 | target platform or look for "Usage:" in metrics_client.cc. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 97 | |
| 98 | |
| 99 | ================================================================================ |
| 100 | The Metrics Daemon: metrics_daemon |
| 101 | ================================================================================ |
| 102 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 103 | metrics_daemon is a daemon that runs in the background on the target platform |
| 104 | and is intended for passive or ongoing metrics collection, or metrics collection |
| 105 | requiring feedback from multiple modules. For example, it listens to D-Bus |
| 106 | signals related to the user session and screen saver states to determine if the |
| 107 | user is actively using the device or not and generates the corresponding |
| 108 | data. The metrics daemon uses libmetrics to send the data to Chrome. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 109 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 110 | The recommended way to generate metrics data from a module is to link and use |
| 111 | libmetrics directly. However, the module could instead send signals to or |
| 112 | communicate in some alternative way with the metrics daemon. Then the metrics |
| 113 | daemon needs to monitor for the relevant events and take appropriate action -- |
| 114 | for example, aggregate data and send the histogram samples. |
Darin Petkov | c2bf95f | 2010-06-21 16:27:52 -0700 | [diff] [blame] | 115 | |
| 116 | |
| 117 | ================================================================================ |
| 118 | FAQ |
| 119 | ================================================================================ |
| 120 | |
| 121 | Q. What should my histogram's |min| and |max| values be set at? |
| 122 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 123 | A. You should set the values to a range that covers the vast majority of samples |
| 124 | that would appear in the field. Note that samples below the |min| will still |
| 125 | be collected in the underflow bucket and samples above the |max| will end up |
| 126 | in the overflow bucket. Also, the reported mean of the data will be correct |
| 127 | regardless of the range. |
Darin Petkov | c2bf95f | 2010-06-21 16:27:52 -0700 | [diff] [blame] | 128 | |
| 129 | Q. How many buckets should I use in my histogram? |
| 130 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 131 | A. You should allocate as many buckets as necessary to perform proper analysis |
| 132 | on the collected data. Note, however, that the memory allocated in Chrome for |
| 133 | each histogram is proportional to the number of buckets. Therefore, it is |
| 134 | strongly recommended to keep this number low (e.g., 50 is normal, while 100 |
| 135 | is probably high). |
Darin Petkov | c2bf95f | 2010-06-21 16:27:52 -0700 | [diff] [blame] | 136 | |
| 137 | Q. When should I use an enumeration (linear) histogram vs. a regular |
| 138 | (exponential) histogram? |
| 139 | |
Darin Petkov | fd55798 | 2010-10-01 15:11:44 -0700 | [diff] [blame^] | 140 | A. Enumeration histograms should really be used only for sampling enumerated |
| 141 | events and, in some cases, percentages. Normally, you should use a regular |
| 142 | histogram with exponential bucket layout that provides higher resolution at |
| 143 | the low end of the range and lower resolution at the high end. Regular |
| 144 | histograms are generally used for collecting performance data (e.g., timing, |
| 145 | memory usage, power) as well as aggregated event counts. |