Metrics: Update README to reflect recent changes.
The updates include:
- Mention the need for "Consent To Send Stats" to exists and the new
AreMetricsEnabled API.
- Replace wiki with XML references (need to add an internal only document
somewhere too).
- Reformat to take full advantage of 80-character lines.
BUG=none
TEST=none
Change-Id: Idbe06e70d5d15f1f8dbbb9475f38a1b0becbca32
Review URL: http://codereview.chromium.org/3573007
diff --git a/metrics/README b/metrics/README
index 677e6b7..1519648 100644
--- a/metrics/README
+++ b/metrics/README
@@ -2,35 +2,32 @@
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:
@@ -42,15 +39,18 @@
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".
================================================================================
@@ -67,55 +67,51 @@
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.
================================================================================
@@ -124,28 +120,26 @@
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.