Telemetry
#########

.. program:: jetstream server

JetStream Server collects anonymized telemetry data that is reported back to Jet Digital Inc., as per the EULA. Sensitive data, such as ip addresses, file names, file size, etc. is anonymized. All data is encrypted during transmission.

.. note::
  To disable collection of telemetry, use the :option:`--disable-telemetry` command line option.


Telemetry Structures
====================

A telemetry session is started by sending over a :ref:`telemetry#telemetry-information-structure`. Telemetry data is then sent approximately every 15 minutes if new data becomes available.


.. _telemetry#telemetry-information-structure:

:index:`Telemetry Information Structure`
----------------------------------------

The Telemetry Information Structure contains the following fields:

.. glossary::
   :sorted:

   :index:`license <pair: Server Information Structure; license>`
      The license key used to the server (See :option:`--license-password`)

   :index:`platform <pair: Server Information Structure; platform>`
      Platform of the server represented by ``linux`` and ``macOS``

   :index:`revision <pair: Server Information Structure; revision>`
      Server revision (See ``revision`` in :ref:`jetstream-api:structure-server-info`)

   :index:`serverId <pair: Server Information Structure; serverId>`
      Server unique ID (See ``serverUid`` in :ref:`jetstream-api:structure-server-info`)

   :index:`startTime <pair: Server Information Structure; startTime>`
      Time when the server was last started


.. _telemetry#telemetry-data-structure:

:index:`Telemetry Data Structure`
---------------------------------

Each telemetry data structure contains the following fields:

.. glossary::
   :sorted:

   :index:`timestamp <pair: Telemetry Data Structure; timestamp>`
      Timestamp for telemetry data

   :index:`key <pair: Telemetry Data Structure; key>`
      Hash of a key identifying telemetry data

   :index:`values <pair: Telemetry Data Structure; values>`
      A list of values associated with the given telemetry key


:index:`Telemetry Data Sets`
============================

.. _telemetry#file-sizes-data-values:

File Sizes Data Values
----------------------

.. index::
  pair: Telemetry Data Sets; file sizes
  pair: Telemetry Data Sets; File Sizes Data Values

``file sizes`` telemetry data is identified by key: ``1418807137``.

===== =============================================== ===========================
Index Description                                     Byte range
===== =============================================== ===========================
 1    Total Number of files
 2    Number of 0 byte files                          0
 3    Number of files 1B or more, less than 1KiB      1 -- 1023
 4    Number of files 1Kib or more, less than 8Kib    1024 -- 8191
 5    Number of files 8Kib or more, less than 64Kib   8192 -- 65535
 6    Number of files 64KiB or more, less than 512KiB 65536 -- 524287
 7    Number of files 512KiB or more, less than 4MiB  524288 -- 4194303
 8    Number of files 4MiB or more, less than 32MiB   4194304 -- 33554431
 9    Number of files 32MiB or more, less than 256MiB 33554432 -- 268435455
10    Number of files 256MiB or more, less than 2GiB  268435456 -- 2147483647
11    Number of files 2GiB or more, less than 16GiB   2147483648 -- 17179869183
12    Number of files 16GiB or more, less than 128GiB 17179869184 -- 137438953471
13    Number of files 128GiB or more                  137438953472 --
===== =============================================== ===========================


.. _telemetry#transfer-sizes-data-values:

Transfer Sizes Data Values
--------------------------

.. index::
  pair: Telemetry Data Sets; transfer sizes
  pair: Telemetry Data Sets; Transfer Sizes Data Values

``transfer sizes`` telemetry data is identified by key: ``2208889336``.

===== =================================================== =============================
Index Description                                         Byte range
===== =================================================== =============================
 1    Total bytes
 2    Number of transfers queued in reported period
 3    Number of transfers less than 1MiB                  0 -- 1048575
 4    Number of transfers 1MiB or more, less than 4Mib    1048576 -- 4194303
 5    Number of transfers 8Kib or more, less than 16Mib   4194304 -- 16777215
 6    Number of transfers 16MiB or more, less than 64MiB  16777216 -- 67108863
 7    Number of transfers 64MiB or more, less than 256MiB 67108864 -- 268435455
 8    Number of transfers 256MiB or more, less than 1GiB  268435456 -- 1073741823
 9    Number of transfers 1GiB or more, less than 4GiB    1073741824 -- 4294967295
10    Number of transfers 4GiB or more, less than 16GiB   4294967296 -- 17179869183
11    Number of transfers 16GiB or more, less than 64GiB  17179869184 -- 68719476735
12    Number of transfers 64GiB or more, less than 256GiB 68719476736 -- 274877906943
13    Number of transfers 256GiB or more, less than 1TiB  274877906944 -- 1099511627775
14    Number of transfers 1TiB or more                    1099511627776 --
===== =================================================== =============================


.. _telemetry#transfer-status-data-values:

Transfer Status Data Values
---------------------------

.. index::
  pair: Telemetry Data Sets; transfer status
  pair: Telemetry Data Sets; Transfer Status Data Values

``transfer status`` telemetry data is identified by key: ``4185460380``.

===== ===============================================
Index Description
===== ===============================================
1     Number of queued transfers in reported period
2     Number of started transfers in reported period
3     Number of completed transfers in reported period
4     Number of failed transfers in reported period
===== ===============================================


.. _telemetry#round-trip-times-data-values:

Round Trip Times Data Values
----------------------------

.. index::
  pair: Telemetry Data Sets; round trip times
  pair: Telemetry Data Sets; Round Trip Times Data Values

``round trip times`` telemetry data is identified by key: ``4229049640``.

===== ===============================================
Index Description
===== ===============================================
1     Time offset representing start of sampling period (relative to ``timestamp`` in :ref:`telemetry#telemetry-data-structure`)
2     Time offset representing end of sampling period (relative to ``timestamp`` in :ref:`telemetry#telemetry-data-structure`)
3     Number of entries in reported period
4     Minimum Round Trip Time in reported period
5     Maximum Round Trip Time in reported period
6     Mean Round Trip Time in reported period
7     Round Trip Time variance in reported period
===== ===============================================


.. _telemetry#transfer-rates-data-values:

Transfer Rates Data Values
--------------------------

Transfer rates are a short term averge of how fast data is being transferred.

.. index::
  pair: Telemetry Data Sets; transfer rates
  pair: Telemetry Data Sets; Transfer Rates Data Values

``transfer rates`` telemetry data is identified by key: ``4160655433``.

===== ===============================================
Index Description
===== ===============================================
1     Time offset representing start of sampling period (relative to ``timestamp`` in :ref:`telemetry#telemetry-data-structure`)
2     Time offset representing end of sampling period (relative to ``timestamp`` in :ref:`telemetry#telemetry-data-structure`)
3     Number of entries in reported period
4     Minimum Transfer Rate (bytes/sec) in reported period
5     Maximum Transfer Rate (bytes/sec) in reported period
6     Mean Transfer Rate (bytes/sec) in reported period
7     Transfer Rate variance in reported period
===== ===============================================


.. _telemetry#transmission-rates-data-values:

Transmission Rates Data Values
------------------------------

Transmission rates are a short term averge of how much network bandwidth is being used by transfers.

.. index::
  pair: Telemetry Data Sets; transmission rates
  pair: Telemetry Data Sets; Transmission Rates Data Values

``transmission rates`` telemetry data is identified by key: ``3920873570``.

===== ===============================================
Index Description
===== ===============================================
1     Time offset representing start of sampling period (relative to ``timestamp`` in :ref:`telemetry#telemetry-data-structure`)
2     Time offset representing end of sampling period (relative to ``timestamp`` in :ref:`telemetry#telemetry-data-structure`)
3     Number of files in reported period
4     Minimum Transmission Rate (bytes/sec) in reported period
5     Maximum Transmission Rate (bytes/sec) in reported period
6     Mean Transmission Rate (bytes/sec) in reported period
7     Transmission Rate variance in reported period
===== ===============================================
