Metrics: Update README to reflect recent changes.

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:

                                     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".

================================================================================

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.

================================================================================

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.