blob: 1519648373c2baf4d8ceb1d78f0d1df1a376ef8a [file] [log] [blame]
Darin Petkov4fd6d3f2010-05-11 09:47:43 -07001Copyright (c) 2010 The Chromium OS Authors. All rights reserved.
2Use of this source code is governed by a BSD-style license that can be
3found in the LICENSE file.
Darin Petkov65b01462010-04-14 13:32:20 -07004
Darin Petkovfd557982010-10-01 15:11:44 -07005The Chrome OS "metrics" package contains utilities for client-side user metric
6collection. The collected data is sent to Chrome for transport to the UMA
7server.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -07008
9
10================================================================================
11The Metrics Library: libmetrics
12================================================================================
13
Darin Petkovfd557982010-10-01 15:11:44 -070014libmetrics is a small library that implements the basic C and C++ API for
15metrics collection. All metrics collection is funneled through this library. The
16easiest and recommended way for a client-side module to collect user metrics is
17to link libmetrics and use its APIs to send metrics to Chrome for transport to
18UMA. In order to use the library in a module, you need to do the following:
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070019
Darin Petkovfd557982010-10-01 15:11:44 -070020- Add a dependence (DEPEND and RDEPEND) on chromeos-base/metrics to the module's
21 ebuild.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070022
Darin Petkovfd557982010-10-01 15:11:44 -070023- 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 Petkov4fd6d3f2010-05-11 09:47:43 -070027
28- To access the metrics library API in the module, include the
Darin Petkovc80dd922010-05-14 09:12:36 -070029 <metrics/metrics_library.h> header file. The file is installed in
Darin Petkovfd557982010-10-01 15:11:44 -070030 $SYSROOT/usr/include/ when the metrics library is built and installed.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070031
Darin Petkovfc91b422010-05-12 13:05:45 -070032- 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 Petkovfd557982010-10-01 15:11:44 -070042 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 Petkov4fd6d3f2010-05-11 09:47:43 -070045
Darin Petkov32e1df92010-06-17 17:05:06 -070046 For more information on the C API see c_metrics_library.h.
47
Darin Petkovfd557982010-10-01 15:11:44 -070048- 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 Petkov4fd6d3f2010-05-11 09:47:43 -070054
55
56================================================================================
57Histogram Naming Convention
58================================================================================
59
60Use TrackerArea.MetricName. For example:
61
62Logging.CrashCounter
63Network.TimeToDrop
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070064
65
66================================================================================
67Server Side
68================================================================================
69
Darin Petkovfd557982010-10-01 15:11:44 -070070If the histogram data is visible in about:histograms, it will be sent by an
71official Chrome build to UMA, assuming the user has opted into metrics
72collection. To make the histogram visible on "chromedashboard", the histogram
73description 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).
75Include the string "Chrome OS" in the histogram description so that it's easier
76to distinguish Chrome OS specific metrics from general Chrome histograms.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070077
Darin Petkovfd557982010-10-01 15:11:44 -070078The UMA server logs and keeps the collected field data even if the metric's name
79is not added to the histogram XML. However, the dashboard histogram for that
80metric will show field data as of the histogram XML update date; it will not
81include data for older dates. If past data needs to be displayed, manual
82server-side intervention is required. In other words, one should assume that
83field data collection starts only after the histogram XML has been updated.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070084
85
86================================================================================
87The Metrics Client: metrics_client
88================================================================================
89
Darin Petkovfd557982010-10-01 15:11:44 -070090metrics_client is a simple shell command-line utility for sending histogram
91samples. It's installed under /usr/bin on the target platform and uses
92libmetrics to send the data to Chrome. The utility is useful for generating
93metrics from shell scripts.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070094
Darin Petkovfd557982010-10-01 15:11:44 -070095For usage information and command-line options, run "metrics_client" on the
96target platform or look for "Usage:" in metrics_client.cc.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070097
98
99================================================================================
100The Metrics Daemon: metrics_daemon
101================================================================================
102
Darin Petkovfd557982010-10-01 15:11:44 -0700103metrics_daemon is a daemon that runs in the background on the target platform
104and is intended for passive or ongoing metrics collection, or metrics collection
105requiring feedback from multiple modules. For example, it listens to D-Bus
106signals related to the user session and screen saver states to determine if the
107user is actively using the device or not and generates the corresponding
108data. The metrics daemon uses libmetrics to send the data to Chrome.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -0700109
Darin Petkovfd557982010-10-01 15:11:44 -0700110The recommended way to generate metrics data from a module is to link and use
111libmetrics directly. However, the module could instead send signals to or
112communicate in some alternative way with the metrics daemon. Then the metrics
113daemon needs to monitor for the relevant events and take appropriate action --
114for example, aggregate data and send the histogram samples.
Darin Petkovc2bf95f2010-06-21 16:27:52 -0700115
116
117================================================================================
118FAQ
119================================================================================
120
121Q. What should my histogram's |min| and |max| values be set at?
122
Darin Petkovfd557982010-10-01 15:11:44 -0700123A. 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 Petkovc2bf95f2010-06-21 16:27:52 -0700128
129Q. How many buckets should I use in my histogram?
130
Darin Petkovfd557982010-10-01 15:11:44 -0700131A. 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 Petkovc2bf95f2010-06-21 16:27:52 -0700136
137Q. When should I use an enumeration (linear) histogram vs. a regular
138 (exponential) histogram?
139
Darin Petkovfd557982010-10-01 15:11:44 -0700140A. 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.