services/docs/metrics.rst

   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.