diff --git a/source/clear-linux/concepts/concepts.rst b/source/clear-linux/concepts/concepts.rst index dbb4b680..496e31e5 100644 --- a/source/clear-linux/concepts/concepts.rst +++ b/source/clear-linux/concepts/concepts.rst @@ -15,3 +15,4 @@ details relevant to the |CL| features. bundles-about autospec-about restart + telemetry-about diff --git a/source/clear-linux/concepts/figures/telemetry-about/telemetry-about-1.png b/source/clear-linux/concepts/figures/telemetry-about/telemetry-about-1.png new file mode 100644 index 00000000..37463254 Binary files /dev/null and b/source/clear-linux/concepts/figures/telemetry-about/telemetry-about-1.png differ diff --git a/source/clear-linux/concepts/telemetry-about.rst b/source/clear-linux/concepts/telemetry-about.rst new file mode 100644 index 00000000..b37e6d90 --- /dev/null +++ b/source/clear-linux/concepts/telemetry-about.rst @@ -0,0 +1,82 @@ +.. _telemetry-about: + +Telemetrics +########### + +One of the key features of |CLOSIA| is telemetry, which is used to +monitor system health. Telemetry enables developers to observe and proactively +address issues before end users are impacted. + +*Telemetrics* is a combination word made from: + +* *Telemetry* which is sensing and reporting data. +* *Analytics* which is using visualization and statistical inferencing to make + sense of the reported data. + +|CL| telemetry reports system-level debug/crash information using specialized probes. The +probes monitor system tasks such as :abbr:`swupd (software updater)`, kernel +oops, machine error checks, and BIOS error report table for unhandled hardware +failures. Telemetry enables real-time issue reporting to allow system +developers to quickly focus on an issue and monitor corrective actions. + +|CL| telemetry is fully customizable and can be used during software development +for debugging purposes. You can use **libtelemetry** in your code to create custom +telemetry records. You can also use **telem-record-gen** in script files or call +it from another program. + +Architecture +************ + +|CL| telemetry has two fundamental components, which are shown in figure 1: + +* Client: generates and delivers records to the backend server via the network. +* Backend: captures records sent from the client and displays the cumulative + content through a specialized interface. + + .. note:: + + If you want to capture your own records for analysis, you must set up + your own backend server. + +.. figure:: figures/telemetry-about-1.png + :scale: 75% + :alt: Clear Linux Telemetry Architecture. + + Figure 1: Clear Linux Telemetry Architecture. + +The telemetry client provides the front end of a complete telemetrics solution +and includes the following components: + +* **telemd**, a daemon that prepares the records to send to a telemetrics server or + spools the records on disk in case it cannot successfully deliver them. +* Probes that collect specific types of data from the operating system. +* **libtelemetry**, that telemetrics probes use to create telemetrics records and + send them to the telemd daemon for further processing. + +The telemetry backend provides the server-side component of a complete telemetrics solution and +consists of: + +* Nginx web server. +* Two Flask apps: + + * Collector, an ingestion web app for records received from telemetrics-client probes. + * TelemetryUI, a web app that exposes several views to visualize the telemetry data + and also provides a REST API to perform queries. + +* PostgreSQL as the underlying database server. + +The default telemetry backend server reports back to the |CL| development team +and is not viewable outside the Intel firewall. If you want to collect your +own records, then you must set up your own telemetry backend server. + +Next steps +********** + +To put this concept into practice, see the following resources: + +* :ref:`telemetry-enable` +* :ref:`telemetry-backend` +* `Telemetry feature description`_ + +.. _`Telemetry feature description`: + https://clearlinux.org/features/telemetry diff --git a/source/clear-linux/guides/maintenance/telemetry-enable.rst b/source/clear-linux/guides/maintenance/telemetry-enable.rst index 3f6ed348..6d401226 100644 --- a/source/clear-linux/guides/maintenance/telemetry-enable.rst +++ b/source/clear-linux/guides/maintenance/telemetry-enable.rst @@ -5,11 +5,11 @@ Enable and disable telemetry in Clear Linux |CLOSIA| includes a telemetry solution as part of the OS that records events of interest and reports them back to the development team via the telemetrics -daemon, :command:`telemd`. This functionality is maintained in the -``telemetrics`` software bundle. +daemon, **telemd**. This functionality is maintained in the +**telemetrics** software bundle. .. note:: - The telemetry functionality adheres to `Intel's privacy policies`_ + The telemetry functionality adheres to `Intel privacy policies`_ regarding the collection and use of :abbr:`PII (Personally Identifiable Information)` and is open source. Specifically, no intentionally identifiable information about the user or system owner is collected. @@ -20,10 +20,10 @@ redirect where the records go if they wish to collect records for themselves. Install the telemetry software bundle ************************************* -During the initial installation of |CL| you are requested to join the +During the initial installation of |CL|, you are requested to join the stability enhancement program and allow |CLOSIA| to collect anonymous reports -to improve system stability. If you chose not to join this program at that -time then the telemetry software bundle is not added to your system. +to improve system stability. If you choose not to join this program, then the +telemetry software bundle is not added to your system. To install the telemetry bundle, enter the following command as either the root user or with :command:`sudo` privileges: @@ -104,9 +104,13 @@ To completely remove telemetrics from your system, use the command Additional resources ******************** -https://clearlinux.org/features/telemetry +* `Telemetry feature description`_ +* :ref:`Telemetry architecture` +* :ref:`telemetry-backend` +* https://github.com/clearlinux/telemetrics-client -https://github.com/clearlinux/telemetrics-client - -.. _`Intel's privacy policies`: +.. _`Intel privacy policies`: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html + +.. _`Telemetry feature description`: + https://clearlinux.org/features/telemetry diff --git a/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst index a11c2474..f2f10160 100644 --- a/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst +++ b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst @@ -1,4 +1,4 @@ -.. _telemtry-backend: +.. _telemetry-backend: Create a telemetry backend server in Clear Linux ################################################ @@ -464,14 +464,17 @@ it. Additional resources ******************** -https://clearlinux.org/features/telemetry - -https://github.com/clearlinux/telemetrics-client - -https://github.com/clearlinux/telemetrics-backend +* `Telemetry feature description`_ +* :ref:`Telemetry architecture` +* :ref:`telemetry-enable` +* https://github.com/clearlinux/telemetrics-client +* https://github.com/clearlinux/telemetrics-backend .. _`Clear Linux telemetry backend server overview`: https://github.com/clearlinux/telemetrics-backend .. _`Intel privacy policies`: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html + +.. _`Telemetry feature description`: + https://clearlinux.org/features/telemetry