| Copyright (c) 2010 The Chromium OS Authors. All rights reserved. |
| Use of this source code is governed by a BSD-style license that can be |
| found in the LICENSE file. |
| |
| The Chrome OS "metrics" package contains utilities for client-side user metric |
| collection. |
| When Chrome is installed, Chrome will take care of aggregating and uploading the |
| metrics to the UMA server. |
| When Chrome is not installed (embedded build) and the metrics_uploader USE flag |
| is set, metrics_daemon will aggregate and upload the metrics itself. |
| |
| |
| ================================================================================ |
| The Metrics Library: libmetrics |
| ================================================================================ |
| |
| libmetrics is a small library that implements the basic C and C++ API for |
| metrics collection. All metrics collection is funneled through this library. The |
| easiest and recommended way for a client-side module to collect user metrics is |
| to link libmetrics and use its APIs to send metrics to Chrome for transport to |
| UMA. In order to use the library in a module, you need to do the following: |
| |
| - Add a dependence (DEPEND and RDEPEND) on chromeos-base/metrics to the module's |
| ebuild. |
| |
| - Link the module with libmetrics (for example, by passing -lmetrics to the |
| module's link command). Both libmetrics.so and libmetrics.a are built and |
| installed under $SYSROOT/usr/lib/. Note that by default -lmetrics will link |
| against libmetrics.so, which is preferred. |
| |
| - To access the metrics library API in the module, include the |
| <metrics/metrics_library.h> header file. The file is installed in |
| $SYSROOT/usr/include/ when the metrics library is built and installed. |
| |
| - The API is documented in metrics_library.h under src/platform/metrics/. Before |
| using the API methods, a MetricsLibrary object needs to be constructed and |
| initialized through its Init method. |
| |
| For more information on the C API see c_metrics_library.h. |
| |
| - Samples are sent to Chrome only if the "/home/chronos/Consent To Send Stats" |
| file exists or the metrics are declared enabled in the policy file (see the |
| AreMetricsEnabled API method). |
| |
| - On the target platform, shortly after the sample is sent, it should be visible |
| in Chrome through "about:histograms". |
| |
| |
| ================================================================================ |
| Histogram Naming Convention |
| ================================================================================ |
| |
| Use TrackerArea.MetricName. For example: |
| |
| Logging.CrashCounter |
| Network.TimeToDrop |
| |
| |
| ================================================================================ |
| Server Side |
| ================================================================================ |
| |
| If the histogram data is visible in about:histograms, it will be sent by an |
| official Chrome build to UMA, assuming the user has opted into metrics |
| collection. To make the histogram visible on "chromedashboard", the histogram |
| description XML file needs to be updated (steps 2 and 3 after following the |
| "Details on how to add your own histograms" link under the Histograms tab). |
| Include the string "Chrome OS" in the histogram description so that it's easier |
| to distinguish Chrome OS specific metrics from general Chrome histograms. |
| |
| The UMA server logs and keeps the collected field data even if the metric's name |
| is not added to the histogram XML. However, the dashboard histogram for that |
| metric will show field data as of the histogram XML update date; it will not |
| include data for older dates. If past data needs to be displayed, manual |
| server-side intervention is required. In other words, one should assume that |
| field data collection starts only after the histogram XML has been updated. |
| |
| |
| ================================================================================ |
| The Metrics Client: metrics_client |
| ================================================================================ |
| |
| metrics_client is a simple shell command-line utility for sending histogram |
| samples and user actions. It's installed under /usr/bin on the target platform |
| and uses libmetrics to send the data to Chrome. The utility is useful for |
| generating metrics from shell scripts. |
| |
| For usage information and command-line options, run "metrics_client" on the |
| target platform or look for "Usage:" in metrics_client.cc. |
| |
| |
| ================================================================================ |
| The Metrics Daemon: metrics_daemon |
| ================================================================================ |
| |
| metrics_daemon is a daemon that runs in the background on the target platform |
| and is intended for passive or ongoing metrics collection, or metrics collection |
| requiring feedback from multiple modules. For example, it listens to D-Bus |
| signals related to the user session and screen saver states to determine if the |
| user is actively using the device or not and generates the corresponding |
| data. The metrics daemon uses libmetrics to send the data to Chrome. |
| |
| The recommended way to generate metrics data from a module is to link and use |
| libmetrics directly. However, the module could instead send signals to or |
| communicate in some alternative way with the metrics daemon. Then the metrics |
| daemon needs to monitor for the relevant events and take appropriate action -- |
| for example, aggregate data and send the histogram samples. |
| |
| |
| ================================================================================ |
| FAQ |
| ================================================================================ |
| |
| Q. What should my histogram's |min| and |max| values be set at? |
| |
| A. You should set the values to a range that covers the vast majority of samples |
| that would appear in the field. Note that samples below the |min| will still |
| be collected in the underflow bucket and samples above the |max| will end up |
| in the overflow bucket. Also, the reported mean of the data will be correct |
| regardless of the range. |
| |
| Q. How many buckets should I use in my histogram? |
| |
| A. You should allocate as many buckets as necessary to perform proper analysis |
| on the collected data. Note, however, that the memory allocated in Chrome for |
| each histogram is proportional to the number of buckets. Therefore, it is |
| strongly recommended to keep this number low (e.g., 50 is normal, while 100 |
| is probably high). |
| |
| Q. When should I use an enumeration (linear) histogram vs. a regular |
| (exponential) histogram? |
| |
| A. Enumeration histograms should really be used only for sampling enumerated |
| events and, in some cases, percentages. Normally, you should use a regular |
| histogram with exponential bucket layout that provides higher resolution at |
| the low end of the range and lower resolution at the high end. Regular |
| histograms are generally used for collecting performance data (e.g., timing, |
| memory usage, power) as well as aggregated event counts. |