README.md
1 Metricsd 2 ======== 3 4 The metricsd daemon is used to gather metrics from the platform and application, 5 aggregate them and upload them periodically to a server. 6 The metrics will then be available in their aggregated form to the developer 7 for analysis. 8 9 Three components are provided to interact with `metricsd`: `libmetrics`, 10 `metrics_collector` and `metrics_client`. 11 12 The Metrics Library: libmetrics 13 ------------------------------- 14 15 `libmetrics` is a small library that implements the basic C++ API for 16 metrics collection. All metrics collection is funneled through this library. The 17 easiest and recommended way for a client-side module to collect user metrics is 18 to link `libmetrics` and use its APIs to send metrics to `metricsd` for transport to 19 UMA. 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 34 Server Side 35 ----------- 36 37 You will be able to see all uploaded metrics on the metrics dashboard, 38 accessible via the developer console. 39 40 *** note 41 It usually takes a day for metrics to be available on the dashboard. 42 *** 43 44 45 The Metrics Client: metrics_client 46 ---------------------------------- 47 48 `metrics_client` is a simple shell command-line utility for sending histogram 49 samples and querying `metricsd`. It's installed under `/system/bin` on the target 50 platform and uses `libmetrics`. 51 52 For usage information and command-line options, run `metrics_client` on the 53 target platform or look for "Usage:" in `metrics_client.cc`. 54 55 56 The Metrics Daemon: metricsd 57 ---------------------------- 58 59 `metricsd` is the daemon that listens for metrics logging calls (via Binder), 60 aggregates the metrics and uploads them periodically. This daemon should start as 61 early 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 75 The Metrics Collector: metrics_collector 76 ---------------------------------------- 77 78 metrics_collector is a daemon that runs in the background on the target platform, 79 gathers health information about the system and maintains long running counters 80 (ex: number of crashes per week). 81 82 The recommended way to generate metrics data from a module is to link and use 83 libmetrics directly. However, we may not want to add a dependency on libmetrics 84 to some modules (ex: kernel). In this case, we can add a collector to 85 metrics_collector that will, for example, take measurements and report them 86 periodically to metricsd (this is the case for the disk utilization histogram). 87 88 89 FAQ 90 --- 91 92 ### What should my histogram's |min| and |max| values be set at? 93 94 You should set the values to a range that covers the vast majority of samples 95 that would appear in the field. Note that samples below the |min| will still 96 be collected in the underflow bucket and samples above the |max| will end up 97 in the overflow bucket. Also, the reported mean of the data will be correct 98 regardless of the range. 99 100 ### How many buckets should I use in my histogram? 101 102 You should allocate as many buckets as necessary to perform proper analysis 103 on the collected data. Note, however, that the memory allocated in metricsd 104 for each histogram is proportional to the number of buckets. Therefore, it is 105 strongly recommended to keep this number low (e.g., 50 is normal, while 100 106 is probably high). 107 108 ### When should I use an enumeration (linear) histogram vs. a regular (exponential) histogram? 109 110 Enumeration histograms should really be used only for sampling enumerated 111 events and, in some cases, percentages. Normally, you should use a regular 112 histogram with exponential bucket layout that provides higher resolution at 113 the low end of the range and lower resolution at the high end. Regular 114 histograms are generally used for collecting performance data (e.g., timing, 115 memory 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
