Metrics: Update README to reflect recent changes.

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 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:
+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.
+- 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.
+- 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.
+  $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/.
+  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".
+- 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 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.
+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 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 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.
+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.
+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.
+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.
+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.
+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).
+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.
+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.