2010-05-11 18:47:43 +02:00
|
|
|
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++ 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_library.h> header file. The file is installed in
|
|
|
|
|
$SYSROOT/usr/include/ when the metrics library is built and
|
|
|
|
|
installed.
|
|
|
|
|
|
|
|
|
|
- Currently, the API includes two static methods:
|
|
|
|
|
|
|
|
|
|
bool MetricsLibrary::SendToChrome(const std::string& name, int sample,
|
|
|
|
|
int min, int max, int nbuckets)
|
|
|
|
|
sends a sample for a regular (exponential) histogram.
|
|
|
|
|
|
|
|
|
|
bool MetricsLibrary::SendEnumToChrome(const std::string& name, int sample,
|
|
|
|
|
int max)
|
|
|
|
|
sends a sample for an enumeration (linear) histogram.
|
|
|
|
|
|
|
|
|
|
See API documentation in metrics_library.h under
|
|
|
|
|
src/platform/metrics/.
|
|
|
|
|
|
|
|
|
|
TODO: It might be better to convert the API to a dynamic object.
|
|
|
|
|
|
|
|
|
|
- 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
|
|
|
|
|
Platform.BootTime
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
================================================================================
|
|
|
|
|
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).
|
|
|
|
|
|
|
|
|
|
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.
|
