151 lines
6.7 KiB
Text
151 lines
6.7 KiB
Text
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. The collected data is sent to Chrome for
|
|
transport to the UMA server.
|
|
|
|
|
|
================================================================================
|
|
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 includes two methods:
|
|
|
|
bool MetricsLibrary::SendToUMA(const std::string& name, int sample,
|
|
int min, int max, int nbuckets)
|
|
sends a sample for a regular (exponential) histogram.
|
|
|
|
bool MetricsLibrary::SendEnumToUMA(const std::string& name, int sample,
|
|
int max)
|
|
sends a sample for an enumeration (linear) histogram.
|
|
|
|
Before using these methods, a MetricsLibrary object needs to be
|
|
constructed and initialized through its Init method. See the
|
|
complete API documentation in metrics_library.h under
|
|
src/platform/metrics/.
|
|
|
|
For more information on the C API see c_metrics_library.h.
|
|
|
|
- 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 wiki 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 wiki. However, the
|
|
dashboard histogram for that metric will show field data as of the
|
|
histogram wiki 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 wiki has been updated.
|
|
|
|
|
|
================================================================================
|
|
The Metrics Client: metrics_client
|
|
================================================================================
|
|
|
|
metrics_client is a simple shell command-line utility for sending
|
|
histogram samples. 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.
|