metricsd/README - platform/system/core - Gitiles

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