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 | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 5 | The Chrome OS "metrics" package contains utilities for client-side |
| 6 | user metric collection. The collected data is sent to Chrome for |
| 7 | transport to the UMA server. |
| 8 | |
| 9 | |
| 10 | ================================================================================ |
| 11 | The Metrics Library: libmetrics |
| 12 | ================================================================================ |
| 13 | |
| 14 | libmetrics is a small library that implements the basic C++ API for |
| 15 | metrics collection. All metrics collection is funneled through this |
| 16 | library. The easiest and recommended way for a client-side module to |
| 17 | collect user metrics is to link libmetrics and use its APIs to send |
| 18 | metrics to Chrome for transport to UMA. In order to use the library in |
| 19 | a module, you need to do the following: |
| 20 | |
| 21 | - Add a dependence (DEPEND and RDEPEND) on chromeos-base/metrics to |
| 22 | the module's ebuild. |
| 23 | |
| 24 | - Link the module with libmetrics (for example, by passing -lmetrics |
| 25 | to the module's link command). Both libmetrics.so and libmetrics.a |
| 26 | are built and installed under $SYSROOT/usr/lib/. Note that by |
| 27 | default -lmetrics will link against libmetrics.so, which is |
| 28 | preferred. |
| 29 | |
| 30 | - To access the metrics library API in the module, include the |
Darin Petkov | c80dd92 | 2010-05-14 09:12:36 -0700 | [diff] [blame] | 31 | <metrics/metrics_library.h> header file. The file is installed in |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 32 | $SYSROOT/usr/include/ when the metrics library is built and |
| 33 | installed. |
| 34 | |
Darin Petkov | fc91b42 | 2010-05-12 13:05:45 -0700 | [diff] [blame] | 35 | - The API includes two methods: |
| 36 | |
| 37 | bool MetricsLibrary::SendToUMA(const std::string& name, int sample, |
| 38 | int min, int max, int nbuckets) |
| 39 | sends a sample for a regular (exponential) histogram. |
| 40 | |
| 41 | bool MetricsLibrary::SendEnumToUMA(const std::string& name, int sample, |
| 42 | int max) |
| 43 | sends a sample for an enumeration (linear) histogram. |
| 44 | |
Darin Petkov | 21cd2c5 | 2010-05-12 15:26:16 -0700 | [diff] [blame] | 45 | Before using these methods, a MetricsLibrary object needs to be |
| 46 | constructed and initialized through its Init method. See the |
| 47 | complete API documentation in metrics_library.h under |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 48 | src/platform/metrics/. |
| 49 | |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 50 | - On the target platform, shortly after the sample is sent it should |
| 51 | be visible in Chrome through "about:histograms". |
| 52 | |
| 53 | |
| 54 | ================================================================================ |
| 55 | Histogram Naming Convention |
| 56 | ================================================================================ |
| 57 | |
| 58 | Use TrackerArea.MetricName. For example: |
| 59 | |
| 60 | Logging.CrashCounter |
| 61 | Network.TimeToDrop |
| 62 | Platform.BootTime |
| 63 | |
| 64 | |
| 65 | ================================================================================ |
| 66 | Server Side |
| 67 | ================================================================================ |
| 68 | |
| 69 | If the histogram data is visible in about:histograms, it will be sent |
| 70 | by an official Chrome build to UMA, assuming the user has opted into |
| 71 | metrics collection. To make the histogram visible on |
| 72 | "chromedashboard", the histogram wiki needs to be updated (steps 2 and |
| 73 | 3 after following the "Details on how to add your own histograms" link |
Darin Petkov | 99c64a0 | 2010-06-10 15:46:39 -0700 | [diff] [blame] | 74 | under the Histograms tab). Include the string "Chrome OS" in the |
| 75 | histogram description so that it's easier to distinguish Chrome OS |
| 76 | specific metrics from general Chrome histograms. |
Darin Petkov | 4fd6d3f | 2010-05-11 09:47:43 -0700 | [diff] [blame] | 77 | |
| 78 | The UMA server logs and keeps the collected field data even if the |
| 79 | metric's name is not added to the histogram wiki. However, the |
| 80 | dashboard histogram for that metric will show field data as of the |
| 81 | histogram wiki update date; it will not include data for older |
| 82 | dates. If past data needs to be displayed, manual server-side |
| 83 | intervention is required. In other words, one should assume that field |
| 84 | data collection starts only after the histogram wiki has been updated. |
| 85 | |
| 86 | |
| 87 | ================================================================================ |
| 88 | The Metrics Client: metrics_client |
| 89 | ================================================================================ |
| 90 | |
| 91 | metrics_client is a simple shell command-line utility for sending |
| 92 | histogram samples. It's installed under /usr/bin on the target |
| 93 | platform and uses libmetrics to send the data to Chrome. The utility |
| 94 | is useful for generating metrics from shell scripts. |
| 95 | |
| 96 | For usage information and command-line options, run "metrics_client" |
| 97 | on the target platform or look for "Usage:" in metrics_client.cc. |
| 98 | |
| 99 | |
| 100 | ================================================================================ |
| 101 | The Metrics Daemon: metrics_daemon |
| 102 | ================================================================================ |
| 103 | |
| 104 | metrics_daemon is a daemon that runs in the background on the target |
| 105 | platform and is intended for passive or ongoing metrics collection, or |
| 106 | metrics collection requiring feedback from multiple modules. For |
| 107 | example, it listens to D-Bus signals related to the user session and |
| 108 | screen saver states to determine if the user is actively using the |
| 109 | device or not and generates the corresponding data. The metrics daemon |
| 110 | uses libmetrics to send the data to Chrome. |
| 111 | |
| 112 | The recommended way to generate metrics data from a module is to link |
| 113 | and use libmetrics directly. However, the module could instead send |
| 114 | signals to or communicate in some alternative way with the metrics |
| 115 | daemon. Then the metrics daemon needs to monitor for the relevant |
| 116 | events and take appropriate action -- for example, aggregate data and |
| 117 | send the histogram samples. |