mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-04 16:15:25 +00:00
b931cfa945
Sphinx has been complaining about a number of reStructuredText warnings for a while. Fix all the ones in .rst files. Not asking for review because this is docs only and changing .rst files can't break anything important. DONTBUILD (NPOTB)
131 lines
4.5 KiB
ReStructuredText
131 lines
4.5 KiB
ReStructuredText
.. _services_metrics:
|
|
|
|
============================
|
|
Metrics Collection Framework
|
|
============================
|
|
|
|
The ``services/metrics`` directory contains a generic data metrics
|
|
collecting and persisting framework for Gecko applications.
|
|
|
|
Overview
|
|
========
|
|
|
|
The Metrics framework by itself doesn't do much: it simply provides a
|
|
generic mechanism for collecting and persisting data. It is up to users
|
|
of this framework to drive collection and do something with the obtained
|
|
data. A consumer of this framework is :ref:`healthreport`.
|
|
|
|
Relationship to Telemetry
|
|
-------------------------
|
|
|
|
Telemetry provides similar features to code in this directory. The two
|
|
may be unified in the future.
|
|
|
|
Usage
|
|
=====
|
|
|
|
To use the code in this directory, import Metrics.jsm. e.g.
|
|
|
|
Components.utils.import("resource://gre/modules/Metrics.jsm");
|
|
|
|
This exports a *Metrics* object which holds references to the main JS
|
|
types and functions provided by this feature. Read below for what those
|
|
types are.
|
|
|
|
Metrics Types
|
|
=============
|
|
|
|
``Metrics.jsm`` exports a number of types. They are documented in the
|
|
sections below.
|
|
|
|
Metrics.Provider
|
|
----------------
|
|
|
|
``Metrics.Provider`` is an entity that collects and manages data. Providers
|
|
are typically domain-specific: if you need to collect a new type of data,
|
|
you create a ``Metrics.Provider`` type that does this.
|
|
|
|
Metrics.Measurement
|
|
-------------------
|
|
|
|
A ``Metrics.Measurement`` represents a collection of related pieces/fields
|
|
of data.
|
|
|
|
All data recorded by the metrics framework is modeled as
|
|
``Metrics.Measurement`` instances. Instances of ``Metrics.Measurement``
|
|
are essentially data structure descriptors.
|
|
|
|
Each ``Metrics.Measurement`` consists of a name and version to identify
|
|
itself (and its data) as well as a list of *fields* that this measurement
|
|
holds. A *field* is effectively an entry in a data structure. It consists
|
|
of a name and strongly enumerated type.
|
|
|
|
Metrics.Storage
|
|
---------------
|
|
|
|
This entity is responsible for persisting collected data and state.
|
|
|
|
It currently uses SQLite to store data, but this detail is abstracted away
|
|
in order to facilitate swapping of storage backends.
|
|
|
|
Metrics.ProviderManager
|
|
-----------------------
|
|
|
|
High-level entity coordinating activity among several ``Metrics.Provider``
|
|
instances.
|
|
|
|
Providers and Measurements
|
|
==========================
|
|
|
|
The most important types in this framework are ``Metrics.Provider`` and
|
|
``Metrics.Measurement``, henceforth known as ``Provider`` and
|
|
``Measurement``, respectively. As you will see, these two types go
|
|
hand in hand.
|
|
|
|
A ``Provider`` is an entity that *provides* data about a specific subsystem
|
|
or feature. They do this by recording data to specific ``Measurement``
|
|
types. Both ``Provider`` and ``Measurement`` are abstract base types.
|
|
|
|
A ``Measurement`` implementation defines a name and version. More
|
|
importantly, it also defines its storage requirements and how
|
|
previously-stored values are serialized.
|
|
|
|
Storage allocation is performed by communicating with the SQLite
|
|
backend. There is a startup function that tells SQLite what fields the
|
|
measurement is recording. The storage backend then registers these in
|
|
the database. Internally, this is creating a new primary key for
|
|
individual fields so later storage operations can directly reference
|
|
these primary keys in order to retrieve data without having to perform
|
|
complicated joins.
|
|
|
|
A ``Provider`` can be thought of as a collection of ``Measurement``
|
|
implementations. e.g. an Addons provider may consist of a measurement
|
|
for all *current* add-ons as well as a separate measurement for
|
|
historical counts of add-ons. A provider's primary role is to take
|
|
metrics data and write it to various measurements. This effectively
|
|
persists the data to SQLite.
|
|
|
|
Data is emitted from providers in either a push or pull based mechanism.
|
|
In push-based scenarios, the provider likely subscribes to external
|
|
events (e.g. observer notifications). An event of interest can occur at
|
|
any time. When it does, the provider immediately writes the event of
|
|
interest to storage or buffers it for eventual writing. In pull-based
|
|
scenarios, the provider is periodically queried and asked to populate
|
|
data.
|
|
|
|
SQLite Storage
|
|
==============
|
|
|
|
``Metrics.Storage`` provides an interface for persisting metrics data to a
|
|
SQLite database.
|
|
|
|
The storage API organizes values by fields. A field is a named member of
|
|
a ``Measurement`` that has specific type and retention characteristics.
|
|
Some example field types include:
|
|
|
|
* Last text value
|
|
* Last numeric value for a given day
|
|
* Discrete text values for a given day
|
|
|
|
See ``storage.jsm`` for more.
|