kuserfeedback/docs/user-feedback-telemetry.qdoc

0001 /*
0002     SPDX-FileCopyrightText: 2017 Volker Krause <vkrause@kde.org>
0003
0004     SPDX-License-Identifier: MIT
0005 */
0006
0007 /*!
0008     \page user-feedback-telemetry.html
0009     \previouspage UserFeedback Manual
0010     \nextpage Surveys
0011     \title Telemetry
0012
0013     \section1 Overview
0014
0015     Telemetry for a product consists of a set of data sources. Each data source
0016     can be a scalar, list or map, and consists of one or more elements.
0017
0018     \section1 Data Model
0019
0020     A data source represents a logically grouped and indivisible set of telemetry
0021     data of the application.
0022
0023     If you are familiar with JSON, it might be useful to see the data model as
0024     JSON structures with a depth limit of two.
0025
0026     \section2 Source Type
0027
0028     A data source has one of the following types:
0029     \list
0030         \li Scalar. A scalar source transmits a single sample of its elements.
0031         A typical example would be a OS type/version source.
0032         \li List. A list source transmits a sequence of its elements. The size
0033         of that sequence is not pre-defined and can be empty. A typical example
0034         would be the users screen configuration.
0035         \li Map. A map source transmits a set of its elements keyed by a string
0036         identifier. Map keys are not pre-defined but can contain arbitrary values.
0037         A typical example would be the usage ratios of different views of the application.
0038     \endlist
0039
0040     The type of a data source is static and defined in the product schema.
0041
0042     \section2 Elements
0043
0044     Each data source has one or more elements. Elements are named fields that contain
0045     values of basic data types, and are fixed and pre-defined in the product schema.
0046
0047     The following data types are supported for source elements:
0048     \list
0049         \li Boolean
0050         \li Integer
0051         \li Float
0052         \li String
0053     \endlist
0054
0055
0056     \section1 Aggregations
0057
0058     Aggregations of telemetry data have no impact on users, they purely serve analytics.
0059     Aggregations use one or more data source elements as input. The following aggregations
0060     are currently implemented:
0061
0062     \list
0063         \li Category. The category aggregator counts the amount of samples grouped by the
0064         value of the selected data source element. It can be used on any element which contains
0065         a reasonably small set of discrete values. A typical example would be the OS type.
0066         \li Numeric. The numeric aggregator computes the minimum/maximum and median values of
0067         the selected data source element. It can be used on any element which contains numeric
0068         values. A typical example would be the start count or usage time of the application.
0069         \li RatioSet. The ratio set aggregator shows the distribution of a map data source
0070         containing normalized numeric data. This is typically used for the usage ratio of
0071         different views or features in the application.
0072     \endlist
0073 */