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
This commit is contained in:
Darin Petkov
parent
dd6a8db06e
commit
fd55798dc0
146
metrics/README
146
metrics/README
|
|
@ -2,35 +2,32 @@ 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:
|
||||
|
||||
|
|
@ -42,15 +39,18 @@ a module, you need to do the following:
|
|||
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 @@ 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.
|
||||
|
||||
|
||||
================================================================================
|
||||
|
|
@ -124,28 +120,26 @@ 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue