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.

- Samples are sent to Chrome only if the "/home/chronos/Consent To Send Stats"
  file exists (see the AreMetricsEnabled API method). Normally, this file is
  created when the user opts into metrics collection.

- 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
description XML file 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 XML. However, the dashboard histogram for that
metric will show field data as of the histogram XML 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 XML 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.