First draft of the metrics doc.

Review URL: http://codereview.chromium.org/1989004

metrics/README

@@ -1,8 +1,115 @@
-This packages contains all scripts and programs assoicated with metrics
-collection for both Chrome's User Metrics Server and automated performance
-metrics collection via Autotest. 
+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 package includes the metrics daemon for Chrome OS.  This program
-runs as a daemon and collects events by polling and listening for
-d-bus signals. It then adds timing (if needed) and sends the events
-to Chrome for transport to the UMA server at Google.
+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.