metrics/README

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.