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