The Tor Browser / file comparison
comparison: services/docs/metrics.rst
services/docs/metrics.rst
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
equal
deleted
inserted
replaced
| -1:000000000000 | 0:646a91492b83 |
|---|---|
| 1 .. _services_metrics: | |
| 2 | |
| 3 ============================ | |
| 4 Metrics Collection Framework | |
| 5 ============================ | |
| 6 | |
| 7 The ``services/metrics`` directory contains a generic data metrics | |
| 8 collecting and persisting framework for Gecko applications. | |
| 9 | |
| 10 Overview | |
| 11 ======== | |
| 12 | |
| 13 The Metrics framework by itself doesn't do much: it simply provides a | |
| 14 generic mechanism for collecting and persisting data. It is up to users | |
| 15 of this framework to drive collection and do something with the obtained | |
| 16 data. A consumer of this framework is :ref:`firefox_health_report`. | |
| 17 | |
| 18 Relationship to Telemetry | |
| 19 ------------------------- | |
| 20 | |
| 21 Telemetry provides similar features to code in this directory. The two | |
| 22 may be unified in the future. | |
| 23 | |
| 24 Usage | |
| 25 ===== | |
| 26 | |
| 27 To use the code in this directory, import Metrics.jsm. e.g. | |
| 28 | |
| 29 Components.utils.import("resource://gre/modules/Metrics.jsm"); | |
| 30 | |
| 31 This exports a *Metrics* object which holds references to the main JS | |
| 32 types and functions provided by this feature. Read below for what those | |
| 33 types are. | |
| 34 | |
| 35 Metrics Types | |
| 36 ============= | |
| 37 | |
| 38 ``Metrics.jsm`` exports a number of types. They are documented in the | |
| 39 sections below. | |
| 40 | |
| 41 Metrics.Provider | |
| 42 ---------------- | |
| 43 | |
| 44 ``Metrics.Provider`` is an entity that collects and manages data. Providers | |
| 45 are typically domain-specific: if you need to collect a new type of data, | |
| 46 you create a ``Metrics.Provider`` type that does this. | |
| 47 | |
| 48 Metrics.Measurement | |
| 49 ------------------- | |
| 50 | |
| 51 A ``Metrics.Measurement`` represents a collection of related pieces/fields | |
| 52 of data. | |
| 53 | |
| 54 All data recorded by the metrics framework is modeled as | |
| 55 ``Metrics.Measurement`` instances. Instances of ``Metrics.Measurement`` | |
| 56 are essentially data structure descriptors. | |
| 57 | |
| 58 Each ``Metrics.Measurement`` consists of a name and version to identify | |
| 59 itself (and its data) as well as a list of *fields* that this measurement | |
| 60 holds. A *field* is effectively an entry in a data structure. It consists | |
| 61 of a name and strongly enumerated type. | |
| 62 | |
| 63 Metrics.Storage | |
| 64 --------------- | |
| 65 | |
| 66 This entity is responsible for persisting collected data and state. | |
| 67 | |
| 68 It currently uses SQLite to store data, but this detail is abstracted away | |
| 69 in order to facilitate swapping of storage backends. | |
| 70 | |
| 71 Metrics.ProviderManager | |
| 72 ----------------------- | |
| 73 | |
| 74 High-level entity coordinating activity among several ``Metrics.Provider`` | |
| 75 instances. | |
| 76 | |
| 77 Providers and Measurements | |
| 78 ========================== | |
| 79 | |
| 80 The most important types in this framework are ``Metrics.Provider`` and | |
| 81 ``Metrics.Measurement``, henceforth known as ``Provider`` and | |
| 82 ``Measurement``, respectively. As you will see, these two types go | |
| 83 hand in hand. | |
| 84 | |
| 85 A ``Provider`` is an entity that *provides* data about a specific subsystem | |
| 86 or feature. They do this by recording data to specific ``Measurement`` | |
| 87 types. Both ``Provider`` and ``Measurement`` are abstract base types. | |
| 88 | |
| 89 A ``Measurement`` implementation defines a name and version. More | |
| 90 importantly, it also defines its storage requirements and how | |
| 91 previously-stored values are serialized. | |
| 92 | |
| 93 Storage allocation is performed by communicating with the SQLite | |
| 94 backend. There is a startup function that tells SQLite what fields the | |
| 95 measurement is recording. The storage backend then registers these in | |
| 96 the database. Internally, this is creating a new primary key for | |
| 97 individual fields so later storage operations can directly reference | |
| 98 these primary keys in order to retrieve data without having to perform | |
| 99 complicated joins. | |
| 100 | |
| 101 A ``Provider`` can be thought of as a collection of ``Measurement`` | |
| 102 implementations. e.g. an Addons provider may consist of a measurement | |
| 103 for all *current* add-ons as well as a separate measurement for | |
| 104 historical counts of add-ons. A provider's primary role is to take | |
| 105 metrics data and write it to various measurements. This effectively | |
| 106 persists the data to SQLite. | |
| 107 | |
| 108 Data is emitted from providers in either a push or pull based mechanism. | |
| 109 In push-based scenarios, the provider likely subscribes to external | |
| 110 events (e.g. observer notifications). An event of interest can occur at | |
| 111 any time. When it does, the provider immediately writes the event of | |
| 112 interest to storage or buffers it for eventual writing. In pull-based | |
| 113 scenarios, the provider is periodically queried and asked to populate | |
| 114 data. | |
| 115 | |
| 116 SQLite Storage | |
| 117 ============== | |
| 118 | |
| 119 ``Metrics.Storage`` provides an interface for persisting metrics data to a | |
| 120 SQLite database. | |
| 121 | |
| 122 The storage API organizes values by fields. A field is a named member of | |
| 123 a ``Measurement`` that has specific type and retention characteristics. | |
| 124 Some example field types include: | |
| 125 | |
| 126 * Last text value | |
| 127 * Last numeric value for a given day | |
| 128 * Discrete text values for a given day | |
| 129 | |
| 130 See ``storage.jsm`` for more. |
