151 lines
7.2 KiB
Plaintext
151 lines
7.2 KiB
Plaintext
Copyright (C) 2015 The Android Open Source Project
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
================================================================================
|
|
|
|
The Chrome OS "metrics" package contains utilities for client-side user metric
|
|
collection.
|
|
When Chrome is installed, Chrome will take care of aggregating and uploading the
|
|
metrics to the UMA server.
|
|
When Chrome is not installed (embedded build) and the metrics_uploader USE flag
|
|
is set, metrics_daemon will aggregate and upload the metrics itself.
|
|
|
|
|
|
================================================================================
|
|
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:
|
|
|
|
- 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/metrics_library.h> header file. The file is installed in
|
|
$SYSROOT/usr/include/ when the metrics library is built and installed.
|
|
|
|
- The API is documented in metrics_library.h under src/platform/metrics/. Before
|
|
using the API methods, a MetricsLibrary object needs to be constructed and
|
|
initialized through its Init method.
|
|
|
|
For more information on the C API see c_metrics_library.h.
|
|
|
|
- Samples are sent to Chrome only if the "/home/chronos/Consent To Send Stats"
|
|
file exists or the metrics are declared enabled in the policy file (see the
|
|
AreMetricsEnabled API method).
|
|
|
|
- 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:
|
|
|
|
Platform.DailyUseTime
|
|
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
|
|
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 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 and user actions. 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.
|
|
|
|
|
|
================================================================================
|
|
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.
|
|
|
|
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).
|
|
|
|
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.
|