platform_system_core/metricsd/README.md

Metricsd

The metricsd daemon is used to gather metrics from the platform and application, aggregate them and upload them periodically to a server. The metrics will then be available in their aggregated form to the developer for analysis.

Three components are provided to interact with metricsd: libmetrics, metrics_collector and metrics_client.

The Metrics Library: libmetrics

libmetrics is a small library that implements the basic 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 metricsd for transport to UMA. In order to use the library in a module, you need to do the following:

• Add a dependency on the shared library in your Android.mk file: LOCAL_SHARED_LIBRARIES += libmetrics

• To access the metrics library API in the module, include the <metrics/metrics_library.h> header file.

• The API is documented in metrics_library.h. Before using the API methods, a MetricsLibrary object needs to be constructed and initialized through its Init method.

• Samples are uploaded only if the /data/misc/metrics/enabled file exists.

Server Side

You will be able to see all uploaded metrics on the metrics dashboard, accessible via the developer console.

*** note It usually takes a day for metrics to be available on the dashboard.

---

The Metrics Client: metrics_client

metrics_client is a simple shell command-line utility for sending histogram samples and querying metricsd. It's installed under /system/bin on the target platform and uses libmetrics.

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: metricsd

metricsd is the daemon that listens for metrics logging calls (via Binder), aggregates the metrics and uploads them periodically. This daemon should start as early as possible so that depending daemons can log at any time.

metricsd is made of two threads that work as follows:

• The binder thread listens for one-way Binder calls, aggregates the metrics in memory (via base::StatisticsRecorder) and increments the crash counters when a crash is reported. This thread is kept as simple as possible to ensure the maximum throughput possible.
• The uploader thread takes care of backing up the metrics to disk periodically (to avoid losing metrics on crashes), collecting metadata about the client (version number, channel, etc..) and uploading the metrics periodically to the server.

The Metrics Collector: metrics_collector

metrics_collector is a daemon that runs in the background on the target platform, gathers health information about the system and maintains long running counters (ex: number of crashes per week).

The recommended way to generate metrics data from a module is to link and use libmetrics directly. However, we may not want to add a dependency on libmetrics to some modules (ex: kernel). In this case, we can add a collector to metrics_collector that will, for example, take measurements and report them periodically to metricsd (this is the case for the disk utilization histogram).

FAQ

What should my histogram's |min| and |max| values be set at?

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.

How many buckets should I use in my histogram?

You should allocate as many buckets as necessary to perform proper analysis on the collected data. Note, however, that the memory allocated in metricsd 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).

When should I use an enumeration (linear) histogram vs. a regular (exponential) histogram?

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.

How can I test that my histogram was reported correctly?

• Make sure no error messages appear in logcat when you log a sample.
• Run metrics_client -d to dump the currently aggregated metrics. Your histogram should appear in the list.
• Make sure that the aggregated metrics were uploaded to the server successfully (check for an OK message from metricsd in logcat).
• After a day, your histogram should be available on the dashboard.