
"main" ping
===========

.. toctree::
   :maxdepth: 2

This is the "main" Telemetry ping type, whose payload contains most of the measurements that are used to track the performance and health of Firefox in the wild.
It includes histograms and other performance and diagnostic data.

This ping may be triggered for one of many reasons documented by the ``reason`` field:

* ``aborted-session`` - this ping is regularly saved to disk (every 5 minutes), overwriting itself, and deleted at shutdown. If a previous aborted session ping is found at startup, it gets sent to the server. The first aborted-session ping is generated as soon as Telemetry starts
* ``environment-change`` - the :doc:`environment` changed, so the session measurements got reset and a new subsession starts
* ``shutdown`` - triggered when the browser session ends. For the first browsing session, this ping is saved to disk and sent on the next browser restart. From the second browsing session on, this ping is sent immediately on shutdown using the :doc:`../internals/pingsender`, unless the OS is shutting down
* ``daily`` - a session split triggered in 24h hour intervals at local midnight. If an ``environment-change`` ping is generated by the time it should be sent, the daily ping is rescheduled for the next midnight
* ``saved-session`` - the *"classic"* Telemetry payload with measurements covering the whole browser session (only submitted on Android)

.. _sessionsplit:

Most reasons lead to a session split, initiating a new *subsession*. We reset important measurements for those subsessions.

After a new subsession split, the ``internal-telemetry-after-subsession-split`` topic is notified to all the observers. *This is an internal topic and is only meant for internal Telemetry usage.*

.. note::

  ``saved-session`` is sent with a different ping type (``saved-session``, not ``main``), but otherwise has the same format as discussed here. As of Firefox 61 this is sent on Android only.

Structure:

.. code-block:: js

    {
      version: 4,

      info: {
        reason: <string>, // what triggered this ping: "saved-session", "environment-change", "shutdown", ...
        revision: <string>, // the Histograms.json revision
        timezoneOffset: <integer>, // time-zone offset from UTC, in minutes, for the current locale
        previousBuildId: <string>, // null if this is the first run, or the previous build ID is unknown

        sessionId: <uuid>,  // random session id, shared by subsessions
        subsessionId: <uuid>,  // random subsession id
        previousSessionId: <uuid>, // session id of the previous session, null on first run.
        previousSubsessionId: <uuid>, // subsession id of the previous subsession (even if it was in a different session),
                                      // null on first run.

        subsessionCounter: <unsigned integer>, // the running no. of this subsession since the start of the browser session
        profileSubsessionCounter: <unsigned integer>, // the running no. of all subsessions for the whole profile life time

        sessionStartDate: <ISO date>, // hourly precision, ISO date in local time
        subsessionStartDate: <ISO date>, // hourly precision, ISO date in local time
        sessionLength: <integer>, // the session length until now in seconds, monotonic
        subsessionLength: <integer>, // the subsession length in seconds, monotonic

        addons: <string>, // obsolete, use ``environment.addons``
      },

      processes: {...},
      simpleMeasurements: {...},

      // The following properties may all be null if we fail to collect them.
      histograms: {...},
      keyedHistograms: {...},
      chromeHangs: {...}, // removed in firefox 62
      threadHangStats: [...], // obsolete in firefox 57, use the 'bhr' ping
      log: [...], // obsolete in firefox 61, use Event Telemetry or Scalars
      gc: {...},
      fileIOReports: {...},
      addonDetails: {...},
      UIMeasurements: [...],  // Android only
      slowSQL: {...},
      slowSQLstartup: {...},
    }

info
----

sessionLength
~~~~~~~~~~~~~
The length of the current session so far in seconds.
This uses a monotonic clock, so this may mismatch with other measurements that
are not monotonic like calculations based on ``Date.now()``.

Note that this currently does not behave consistently over our supported platforms:

* On Windows this uses ``GetTickCount64()``, which does increase over sleep periods
* On macOS this uses ``mach_absolute_time()``, which does not increase over sleep periods
* On POSIX/Linux this uses ``clock_gettime(CLOCK_MONOTONIC, &ts)``, which should not increase over sleep time

See `bug 1204823 <https://bugzilla.mozilla.org/show_bug.cgi?id=1204823>`_ for details.

subsessionLength
~~~~~~~~~~~~~~~~
The length of this subsession in seconds.
This uses a monotonic clock, so this may mismatch with other measurements that are not monotonic (e.g. based on ``Date.now()``).

Also see the remarks for ``sessionLength`` on platform consistency.

processes
---------
This section contains per-process data.

Structure:

.. code-block:: js

    "processes" : {
      // ... other processes ...
      "parent": {
        scalars: {...},
        keyedScalars: {...},
        // parent process histograms and keyedHistograms are in main payload
      },
      "content": {
        scalars: {...},
        keyedScalars: {...},
        histograms: {...},
        keyedHistograms: {...},
      },
      "gpu": {
        // ...
      }
    }

histograms and keyedHistograms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section contains histograms and keyed histograms accumulated on content processes. Histograms recorded on a content child process have different character than parent histograms. For instance, ``GC_MS`` will be much different in ``processes.content`` as it has to contend with web content, whereas the instance in ``payload.histograms`` has only to contend with browser JS. Also, some histograms may be absent if never recorded on a content child process (``EVENTLOOP_UI_ACTIVITY`` is parent-process-only).

This format was adopted in Firefox 51 via bug 1218576.

scalars and keyedScalars
~~~~~~~~~~~~~~~~~~~~~~~~
This section contains the Scalars that are valid for the current platform. Scalars are only submitted if data was added to them, and are only reported with subsession pings. The recorded scalars are described in the :searchfox:`Scalars.yaml <toolkit/components/telemetry/Scalars.yaml>` file. The ``info.revision`` field indicates the revision of the file that describes the reported scalars.

simpleMeasurements
------------------
This section contains a list of simple measurements, or counters. Only specific simple measurements are supported by the data pipeline.

totalTime
~~~~~~~~~
A non-monotonic integer representing the number of seconds the session has been alive.

addonManager
~~~~~~~~~~~~
As of Firefox 150 this section is no longer present.

Only available in the extended set of measures, it contains a set of counters related to Addons. See `here <https://searchfox.org/mozilla-central/search?q=AddonManagerPrivate.recordSimpleMeasure&redirect=false&case=true>`__ for a list of recorded measures.

maximalNumberOfConcurrentThreads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An integer representing the highest number of threads encountered so far during the session.

startupSessionRestoreReadBytes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows-only integer representing the number of bytes read by the main process up until the session store has finished restoring the windows.

startupSessionRestoreWriteBytes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows-only integer representing the number of bytes written by the main process up until the session store has finished restoring the windows.

startupWindowVisibleReadBytes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows-only integer representing the number of bytes read by the main process up until after a XUL window is made visible.

startupWindowVisibleWriteBytes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows-only integer representing the number of bytes written by the main process up until after a XUL window is made visible.

debuggerAttached
~~~~~~~~~~~~~~~~
A boolean set to true if a debugger is attached to the main process.

shutdownDuration
~~~~~~~~~~~~~~~~
The time, in milliseconds, it took to complete the last shutdown.

failedProfileLockCount
~~~~~~~~~~~~~~~~~~~~~~
The number of times the system failed to lock the user profile.

activeTicks
~~~~~~~~~~~
Integer count of the number of five-second intervals ('ticks') the user was considered 'active' (sending UI events to the window). An extra event is fired immediately when the user becomes active after being inactive. This is for some mouse and gamepad events, and all touch, keyboard, wheel, and pointer events (see :searchfox:`EventStateManager.cpp <dom/events/EventStateManager.cpp#504>`).
This measure might be useful to give a trend of how much a user actually interacts with the browser when compared to overall session duration. It does not take into account whether or not the window has focus or is in the foreground. Just if it is receiving these interaction events.
Note that in ``main`` pings, this measure is reset on subsession splits, while in ``saved-session`` pings it covers the whole browser session.

histograms
----------
This section contains the histograms that are valid for the current platform. ``Flag`` histograms are always created and submitted with a default value of ``false`` if a value of ``true`` is not recorded during the time period. Other histogram types (see :ref:`choosing-histogram-type`) are not created nor submitted if no data was added to them. The type and format of the reported histograms is described by the ``Histograms.json`` file. Its most recent version is available :searchfox:`here <toolkit/components/telemetry/Histograms.json>`. The ``info.revision`` field indicates the revision of the file that describes the reported histograms.

keyedHistograms
---------------
This section contains the keyed histograms available for the current platform.

fileIOReports
-------------
Contains the statistics of main-thread I/O recorded during the execution. Only the I/O stats for the XRE and the profile directories are currently reported, neither of them disclosing the full local path.

Structure:

.. code-block:: js

    "fileIOReports": {
      "{xre}": [
        totalTime, // Accumulated duration of all operations
        creates, // Number of create/open operations
        reads, // Number of read operations
        writes, // Number of write operations
        fsyncs, // Number of fsync operations
        stats, // Number of stat operations
      ],
      "{profile}": [ ... ],
      ...
    }

addonDetails
------------
This section contains per add-on telemetry details, as reported by each add-on provider. The XPI provider is the only one reporting at the time of writing (`see Searchfox <https://searchfox.org/mozilla-central/search?q=setTelemetryDetails&case=true>`_). Telemetry does not manipulate or enforce a specific format for the supplied provider's data.

Structure:

.. code-block:: js

    "addonDetails": {
      "XPI": {
        "adbhelper@mozilla.org": {
          "location": "app-profile",
          "name": "ADB Helper",
          "creator": "Mozilla & Android Open Source Project",
        },
        ...
      },
      ...
    }

slowSQL
-------
This section contains the information about the slow SQL queries for both the main and other threads. The execution of an SQL statement is considered slow if it takes 50ms or more on the main thread or 100ms or more on other threads. Slow SQL statements will be automatically trimmed to 1000 characters. This limit doesn't include the ellipsis and database name, that are appended at the end of the stored statement.

Structure:

.. code-block:: js

    "slowSQL": {
      "mainThread": {
        "Sanitized SQL Statement": [
          1, // the number of times this statement was hit
          200  // the total time (in milliseconds) that was spent on this statement
        ],
        ...
      },
      "otherThreads": {
        "VACUUM /* places.sqlite */": [
          1,
          330
        ],
        ...
      }
    },

slowSQLStartup
--------------
This section contains the slow SQL statements gathered at startup (until the "sessionstore-windows-restored" event is fired). The structure of this section resembles the one for `slowSQL`_.

UIMeasurements
--------------
This section is Android-only and contains UI specific Telemetry measurements and events (`see here <https://searchfox.org/mozilla-central/search?q=UITelemetry.%28addEvent|startSession|stopSession%29&redirect=false&case=false&regexp=true>`_).

Structure:

.. code-block:: js

    "UIMeasurements": [
      {
        "type": "event", // either "session" or "event"
        "action": "action.1",
        "method": "menu",
        "sessions": [],
        "timestamp": 12345,
        "extras": "settings"
      },
      {
        "type": "session",
        "name": "awesomescreen.1",
        "reason": "commit",
        "start": 123,
        "end": 456
      }
      ...
    ],

Version History
---------------

- Firefox 150:

  - Stopped reporting ``simpleMeasurements`` that the pipeline doesn't provide columns for (`bug 2017318 <https://bugzilla.mozilla.org/show_bug.cgi?id=2017318>`_).

- Firefox 142:

  - Stopped reporting ``lateWrites`` (`bug 1972836 <https://bugzilla.mozilla.org/show_bug.cgi?id=1972836>`_).

- Firefox 88:

  - Stopped reporting ``flashVersion`` since Flash is no longer supported. (`bug 1682030 <https://bugzilla.mozilla.org/show_bug.cgi?id=1682030>`_)

- Firefox 61:

  - Stopped reporting ``childPayloads`` (`bug 1443599 <https://bugzilla.mozilla.org/show_bug.cgi?id=1443599>`_).
  - Stopped reporting ``saved-session`` pings on Firefox Desktop (`bug 1443603 <https://bugzilla.mozilla.org/show_bug.cgi?id=1443603>`_).
  - Stopped reporting ``simpleMeasurements.js`` (`bug 1278920 <https://bugzilla.mozilla.org/show_bug.cgi?id=1278920>`_).
  - Stopped reporting ``UITelemetry`` (`bug 1443605 <https://bugzilla.mozilla.org/show_bug.cgi?id=1443605>`_)

- Firefox 62:

  - ``events`` are now reported via the :doc:`../data/event-ping` (`bug 1460595 <https://bugzilla.mozilla.org/show_bug.cgi?id=1460595>`_).

- Firefox 80:

  - Stopped reporting ``GCTelemetry`` (`bug 1482089 <https://bugzilla.mozilla.org/show_bug.cgi?id=1482089>`_).
