blob: 6fec766f0139676fe99c8cb8e6973bcf3fb7b3d2 [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 Petkov4fd6d3f2010-05-11 09:47:43 -07005The Chrome OS "metrics" package contains utilities for client-side
6user metric collection. The collected data is sent to Chrome for
7transport to the UMA server.
8
9
10================================================================================
11The Metrics Library: libmetrics
12================================================================================
13
14libmetrics is a small library that implements the basic C++ API for
15metrics collection. All metrics collection is funneled through this
16library. The easiest and recommended way for a client-side module to
17collect user metrics is to link libmetrics and use its APIs to send
18metrics to Chrome for transport to UMA. In order to use the library in
19a 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 Petkovc80dd922010-05-14 09:12:36 -070031 <metrics/metrics_library.h> header file. The file is installed in
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070032 $SYSROOT/usr/include/ when the metrics library is built and
33 installed.
34
Darin Petkovfc91b422010-05-12 13:05:45 -070035- 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 Petkov21cd2c52010-05-12 15:26:16 -070045 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 Petkov4fd6d3f2010-05-11 09:47:43 -070048 src/platform/metrics/.
49
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070050- On the target platform, shortly after the sample is sent it should
51 be visible in Chrome through "about:histograms".
52
53
54================================================================================
55Histogram Naming Convention
56================================================================================
57
58Use TrackerArea.MetricName. For example:
59
60Logging.CrashCounter
61Network.TimeToDrop
62Platform.BootTime
63
64
65================================================================================
66Server Side
67================================================================================
68
69If the histogram data is visible in about:histograms, it will be sent
70by an official Chrome build to UMA, assuming the user has opted into
71metrics collection. To make the histogram visible on
72"chromedashboard", the histogram wiki needs to be updated (steps 2 and
733 after following the "Details on how to add your own histograms" link
Darin Petkov99c64a02010-06-10 15:46:39 -070074under the Histograms tab). Include the string "Chrome OS" in the
75histogram description so that it's easier to distinguish Chrome OS
76specific metrics from general Chrome histograms.
Darin Petkov4fd6d3f2010-05-11 09:47:43 -070077
78The UMA server logs and keeps the collected field data even if the
79metric's name is not added to the histogram wiki. However, the
80dashboard histogram for that metric will show field data as of the
81histogram wiki update date; it will not include data for older
82dates. If past data needs to be displayed, manual server-side
83intervention is required. In other words, one should assume that field
84data collection starts only after the histogram wiki has been updated.
85
86
87================================================================================
88The Metrics Client: metrics_client
89================================================================================
90
91metrics_client is a simple shell command-line utility for sending
92histogram samples. It's installed under /usr/bin on the target
93platform and uses libmetrics to send the data to Chrome. The utility
94is useful for generating metrics from shell scripts.
95
96For usage information and command-line options, run "metrics_client"
97on the target platform or look for "Usage:" in metrics_client.cc.
98
99
100================================================================================
101The Metrics Daemon: metrics_daemon
102================================================================================
103
104metrics_daemon is a daemon that runs in the background on the target
105platform and is intended for passive or ongoing metrics collection, or
106metrics collection requiring feedback from multiple modules. For
107example, it listens to D-Bus signals related to the user session and
108screen saver states to determine if the user is actively using the
109device or not and generates the corresponding data. The metrics daemon
110uses libmetrics to send the data to Chrome.
111
112The recommended way to generate metrics data from a module is to link
113and use libmetrics directly. However, the module could instead send
114signals to or communicate in some alternative way with the metrics
115daemon. Then the metrics daemon needs to monitor for the relevant
116events and take appropriate action -- for example, aggregate data and
117send the histogram samples.