README.md
1Metricsd
2========
3
4The metricsd daemon is used to gather metrics from the platform and application,
5aggregate them and upload them periodically to a server.
6The metrics will then be available in their aggregated form to the developer
7for analysis.
8
9Three components are provided to interact with `metricsd`: `libmetrics`,
10`metrics_collector` and `metrics_client`.
11
12The Metrics Library: libmetrics
13-------------------------------
14
15`libmetrics` is a small library that implements the basic C++ API for
16metrics collection. All metrics collection is funneled through this library. The
17easiest and recommended way for a client-side module to collect user metrics is
18to link `libmetrics` and use its APIs to send metrics to `metricsd` for transport to
19UMA. In order to use the library in a module, you need to do the following:
20
21- Add a dependency on the shared library in your Android.mk file:
22 `LOCAL_SHARED_LIBRARIES += libmetrics`
23
24- To access the metrics library API in the module, include the
25 <metrics/metrics_library.h> header file.
26
27- The API is documented in `metrics_library.h`. Before using the API methods, a
28 MetricsLibrary object needs to be constructed and initialized through its
29 Init method.
30
31- Samples are uploaded only if the `/data/misc/metrics/enabled` file exists.
32
33
34Server Side
35-----------
36
37You will be able to see all uploaded metrics on the metrics dashboard,
38accessible via the developer console.
39
40*** note
41It usually takes a day for metrics to be available on the dashboard.
42***
43
44
45The Metrics Client: metrics_client
46----------------------------------
47
48`metrics_client` is a simple shell command-line utility for sending histogram
49samples and querying `metricsd`. It's installed under `/system/bin` on the target
50platform and uses `libmetrics`.
51
52For usage information and command-line options, run `metrics_client` on the
53target platform or look for "Usage:" in `metrics_client.cc`.
54
55
56The Metrics Daemon: metricsd
57----------------------------
58
59`metricsd` is the daemon that listens for metrics logging calls (via Binder),
60aggregates the metrics and uploads them periodically. This daemon should start as
61early as possible so that depending daemons can log at any time.
62
63`metricsd` is made of two threads that work as follows:
64
65* The binder thread listens for one-way Binder calls, aggregates the metrics in
66 memory (via `base::StatisticsRecorder`) and increments the crash counters when a
67 crash is reported. This thread is kept as simple as possible to ensure the
68 maximum throughput possible.
69* The uploader thread takes care of backing up the metrics to disk periodically
70 (to avoid losing metrics on crashes), collecting metadata about the client
71 (version number, channel, etc..) and uploading the metrics periodically to the
72 server.
73
74
75The Metrics Collector: metrics_collector
76----------------------------------------
77
78metrics_collector is a daemon that runs in the background on the target platform,
79gathers health information about the system and maintains long running counters
80(ex: number of crashes per week).
81
82The recommended way to generate metrics data from a module is to link and use
83libmetrics directly. However, we may not want to add a dependency on libmetrics
84to some modules (ex: kernel). In this case, we can add a collector to
85metrics_collector that will, for example, take measurements and report them
86periodically to metricsd (this is the case for the disk utilization histogram).
87
88
89FAQ
90---
91
92### What should my histogram's |min| and |max| values be set at?
93
94You should set the values to a range that covers the vast majority of samples
95that would appear in the field. Note that samples below the |min| will still
96be collected in the underflow bucket and samples above the |max| will end up
97in the overflow bucket. Also, the reported mean of the data will be correct
98regardless of the range.
99
100### How many buckets should I use in my histogram?
101
102You should allocate as many buckets as necessary to perform proper analysis
103on the collected data. Note, however, that the memory allocated in metricsd
104for each histogram is proportional to the number of buckets. Therefore, it is
105strongly recommended to keep this number low (e.g., 50 is normal, while 100
106is probably high).
107
108### When should I use an enumeration (linear) histogram vs. a regular (exponential) histogram?
109
110Enumeration histograms should really be used only for sampling enumerated
111events and, in some cases, percentages. Normally, you should use a regular
112histogram with exponential bucket layout that provides higher resolution at
113the low end of the range and lower resolution at the high end. Regular
114histograms are generally used for collecting performance data (e.g., timing,
115memory usage, power) as well as aggregated event counts.
116
117### How can I test that my histogram was reported correctly?
118
119* Make sure no error messages appear in logcat when you log a sample.
120* Run `metrics_client -d` to dump the currently aggregated metrics. Your
121 histogram should appear in the list.
122* Make sure that the aggregated metrics were uploaded to the server successfully
123 (check for an OK message from `metricsd` in logcat).
124* After a day, your histogram should be available on the dashboard.
125