Merge pull request #198 from MCamp859/telemetry-edits

Add telemetry concept to CL docs.

source/clear-linux/concepts/concepts.rst

@@ -15,3 +15,4 @@ details relevant to the |CL| features.
    bundles-about
    autospec-about
    restart
+   telemetry-about

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

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<telemetry-about>`
+*	: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

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<telemetry-about>`
+* :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