From c8bdc52e44b7fbe37576cd68088dedd734801338 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 7 Nov 2018 18:21:54 -0800 Subject: [PATCH 1/5] Corrects syntax error and revises sentence for legibility. Signed-off-by: Michael Vincerra --- source/clear-linux/guides/telemetrics/telemctl.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/clear-linux/guides/telemetrics/telemctl.rst b/source/clear-linux/guides/telemetrics/telemctl.rst index 52e88abe..97db933a 100644 --- a/source/clear-linux/guides/telemetrics/telemctl.rst +++ b/source/clear-linux/guides/telemetrics/telemctl.rst @@ -3,9 +3,10 @@ telemctl options ################ -The |CL-ATTR| telemetry client provides an admin tool called telemctl for -managing the telemetry services and probes. The tool is located in -:file:` /usr/bin`. Running it with no argument results in the following: +The |CL-ATTR| telemetry client provides an admin tool called ``telemctl`` +that is used for managing the telemetry services and probes. The tool is +located in :file:`/usr/bin`. Running it with no argument results in the +following: .. code-block:: bash From 56f94409361a8c5cdb604965b3e62e83ab5eb0f0 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 8 Nov 2018 13:43:28 -0800 Subject: [PATCH 2/5] Renames telemetry-api with a prefix of z so that it appears last. Signed-off-by: Michael Vincerra --- .../guides/telemetrics/telemetry-z-api.rst | 170 ++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 source/clear-linux/guides/telemetrics/telemetry-z-api.rst diff --git a/source/clear-linux/guides/telemetrics/telemetry-z-api.rst b/source/clear-linux/guides/telemetrics/telemetry-z-api.rst new file mode 100644 index 00000000..d8a2fd0b --- /dev/null +++ b/source/clear-linux/guides/telemetrics/telemetry-z-api.rst @@ -0,0 +1,170 @@ +.. _telemetry-api: + +Telemetry API +############# + +Installing the ``telemetrics`` bundle includes the libtelemetry C library, +which exposes an API used by the telemprobd and telempostd daemons. You +can use these in your applications as well. The API documentation is found +in the :file:`telemetry.h` file in `Telemetrics client`_ repository. + +Creating records with telem-record-gen +************************************** + +The telemetrics bundle also provides a record generator tool called +``telem-record-gen``. This tool can be used to create records from shell +scripts, etc., when writing a probe in C is not desirable. Records are sent +to the backend server, and can also be echoed to stdout. + +telem-record-gen usage +====================== + +.. code-block:: bash + + telem-record-gen [OPTIONS] - create and send a custom telemetry record + +.. code-block:: console + + Help Options: + -h, --help Show help options + + Application Options: + -V, --version Print the program version + -s, --severity Severity level (1-4) - (default 1) + -c, --class Classification level_1/level_2/level_3 (required) + -p, --payload Record body (max size = 8k) (required) + -P, --payload-file File to read payload from + -R, --record-version Version number for format of payload (default 1) + -e, --event-id Event id to use in the record + -o, --echo Echo record to stdout + -n, --no-post Do not post record just print + +The :command:`-c` and :command:`-p` options are required; defaults are +supplied for most other options. The maximum payload size is 8k +(8192 bytes). Excess is ignored, regardless of source (file/commandline/ +stdin). An empty payload is allowed, but even an empty payload must be +specified in one of the three ways shown below. + +telem-record-gen examples +========================= + +There are three ways to supply the payload to the record. + +#. On the command line, use the :command:`-p ` option: + + .. code-block:: bash + + telem-record-gen -c a/b/c -n -o -p 'payload goes here' + + .. code-block:: console + + record_format_version: 4 + classification: a/b/c + severity: 1 + machine_id: FFFFFFFF + creation_timestamp: 1539023189 + arch: x86_64 + host_type: innotek GmbH|VirtualBox|1.2 + build: 25180 + kernel_version: 4.14.71-404.lts + payload_format_version: 1 + system_name: clear-linux-os + board_name: VirtualBox|Oracle Corporation + cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz + bios_version: VirtualBox + event_id: 2236710e4fc11e4a646ce956c7802788 + + payload goes here + +#. Specify a file that contains the payload with the option + :command:'-P path/to/file'. + + .. code-block:: bash + + telem-record-gen -c a/b/c -n -o -P ./payload_file.txt + + .. code-block:: console + + record_format_version: 4 + classification: a/b/c + severity: 1 + machine_id: FFFFFFFF + creation_timestamp: 1539023621 + arch: x86_64 + host_type: innotek GmbH|VirtualBox|1.2 + build: 25180 + kernel_version: 4.14.71-404.lts + payload_format_version: 1 + system_name: clear-linux-os + board_name: VirtualBox|Oracle Corporation + cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz + bios_version: VirtualBox + event_id: d73d6040afd7693cccdfece479df9795 + + payload read from file + +#. If the :command:`-p` or :command:`-P` options are absent, the tool reads + from stdin so you can use it in a :file:`heredoc` in scripts. + + .. code-block:: bash + + telem-record-gen -c a/b/c -n -o << HEOF + payload read from stdin + HEOF + + .. code-block:: console + + record_format_version: 4 + classification: a/b/c + severity: 1 + machine_id: FFFFFFFF + creation_timestamp: 1539023621 + arch: x86_64 + host_type: innotek GmbH|VirtualBox|1.2 + build: 25180 + kernel_version: 4.14.71-404.lts + payload_format_version: 1 + system_name: clear-linux-os + board_name: VirtualBox|Oracle Corporation + cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz + bios_version: VirtualBox + event_id: 2f070e8e71679f2b1f28794e3a6c42ee + + payload read from stdin + + .. note:: + + Although only the classification and payload are specified, the tool supplies values for the remaining values. + +Telemetry records and the REST API +================================== + +If you have not configured the telemetry client to keep records locally, you +can view them using the Web UI of the server, or you can query them from the +server using the REST API provided by |CL| telemetrics. The API is +available at :file:`/api/records`, and when queried, returns a JSON +response that contains a list of records. There are several parameters for +filtering queries, similar to the filters available through the telemetryui Records view. + +* classification: The classification of the record +* severity: The severity of the record. Restricted to integer value +* machine_id: The id of the machine where this record was generated on +* build: The build on which the record was generated. Restricted to 256 + characters. +* created_in_days: causes the query to return records created after the last + given days +* created_in_sec: returns the records created after the last given seconds +* limit: The maximum number of records to be returned. + +Next Steps +========== + +* :ref:`telemetry-backend` +* `Telemetrics client`_ + +Related topics +============== + +* :ref:`telemetry-about` + +.. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/ From d5636371f66a43ef1cb9fdb8cf6e86274961b5c8 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 8 Nov 2018 13:44:31 -0800 Subject: [PATCH 3/5] Renames telemetry-api. Signed-off-by: Michael Vincerra --- .../guides/telemetrics/telemetry-api.rst | 170 ------------------ 1 file changed, 170 deletions(-) delete mode 100644 source/clear-linux/guides/telemetrics/telemetry-api.rst diff --git a/source/clear-linux/guides/telemetrics/telemetry-api.rst b/source/clear-linux/guides/telemetrics/telemetry-api.rst deleted file mode 100644 index d8a2fd0b..00000000 --- a/source/clear-linux/guides/telemetrics/telemetry-api.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. _telemetry-api: - -Telemetry API -############# - -Installing the ``telemetrics`` bundle includes the libtelemetry C library, -which exposes an API used by the telemprobd and telempostd daemons. You -can use these in your applications as well. The API documentation is found -in the :file:`telemetry.h` file in `Telemetrics client`_ repository. - -Creating records with telem-record-gen -************************************** - -The telemetrics bundle also provides a record generator tool called -``telem-record-gen``. This tool can be used to create records from shell -scripts, etc., when writing a probe in C is not desirable. Records are sent -to the backend server, and can also be echoed to stdout. - -telem-record-gen usage -====================== - -.. code-block:: bash - - telem-record-gen [OPTIONS] - create and send a custom telemetry record - -.. code-block:: console - - Help Options: - -h, --help Show help options - - Application Options: - -V, --version Print the program version - -s, --severity Severity level (1-4) - (default 1) - -c, --class Classification level_1/level_2/level_3 (required) - -p, --payload Record body (max size = 8k) (required) - -P, --payload-file File to read payload from - -R, --record-version Version number for format of payload (default 1) - -e, --event-id Event id to use in the record - -o, --echo Echo record to stdout - -n, --no-post Do not post record just print - -The :command:`-c` and :command:`-p` options are required; defaults are -supplied for most other options. The maximum payload size is 8k -(8192 bytes). Excess is ignored, regardless of source (file/commandline/ -stdin). An empty payload is allowed, but even an empty payload must be -specified in one of the three ways shown below. - -telem-record-gen examples -========================= - -There are three ways to supply the payload to the record. - -#. On the command line, use the :command:`-p ` option: - - .. code-block:: bash - - telem-record-gen -c a/b/c -n -o -p 'payload goes here' - - .. code-block:: console - - record_format_version: 4 - classification: a/b/c - severity: 1 - machine_id: FFFFFFFF - creation_timestamp: 1539023189 - arch: x86_64 - host_type: innotek GmbH|VirtualBox|1.2 - build: 25180 - kernel_version: 4.14.71-404.lts - payload_format_version: 1 - system_name: clear-linux-os - board_name: VirtualBox|Oracle Corporation - cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz - bios_version: VirtualBox - event_id: 2236710e4fc11e4a646ce956c7802788 - - payload goes here - -#. Specify a file that contains the payload with the option - :command:'-P path/to/file'. - - .. code-block:: bash - - telem-record-gen -c a/b/c -n -o -P ./payload_file.txt - - .. code-block:: console - - record_format_version: 4 - classification: a/b/c - severity: 1 - machine_id: FFFFFFFF - creation_timestamp: 1539023621 - arch: x86_64 - host_type: innotek GmbH|VirtualBox|1.2 - build: 25180 - kernel_version: 4.14.71-404.lts - payload_format_version: 1 - system_name: clear-linux-os - board_name: VirtualBox|Oracle Corporation - cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz - bios_version: VirtualBox - event_id: d73d6040afd7693cccdfece479df9795 - - payload read from file - -#. If the :command:`-p` or :command:`-P` options are absent, the tool reads - from stdin so you can use it in a :file:`heredoc` in scripts. - - .. code-block:: bash - - telem-record-gen -c a/b/c -n -o << HEOF - payload read from stdin - HEOF - - .. code-block:: console - - record_format_version: 4 - classification: a/b/c - severity: 1 - machine_id: FFFFFFFF - creation_timestamp: 1539023621 - arch: x86_64 - host_type: innotek GmbH|VirtualBox|1.2 - build: 25180 - kernel_version: 4.14.71-404.lts - payload_format_version: 1 - system_name: clear-linux-os - board_name: VirtualBox|Oracle Corporation - cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz - bios_version: VirtualBox - event_id: 2f070e8e71679f2b1f28794e3a6c42ee - - payload read from stdin - - .. note:: - - Although only the classification and payload are specified, the tool supplies values for the remaining values. - -Telemetry records and the REST API -================================== - -If you have not configured the telemetry client to keep records locally, you -can view them using the Web UI of the server, or you can query them from the -server using the REST API provided by |CL| telemetrics. The API is -available at :file:`/api/records`, and when queried, returns a JSON -response that contains a list of records. There are several parameters for -filtering queries, similar to the filters available through the telemetryui Records view. - -* classification: The classification of the record -* severity: The severity of the record. Restricted to integer value -* machine_id: The id of the machine where this record was generated on -* build: The build on which the record was generated. Restricted to 256 - characters. -* created_in_days: causes the query to return records created after the last - given days -* created_in_sec: returns the records created after the last given seconds -* limit: The maximum number of records to be returned. - -Next Steps -========== - -* :ref:`telemetry-backend` -* `Telemetrics client`_ - -Related topics -============== - -* :ref:`telemetry-about` - -.. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/ From 35eeed664f3fc260a2cf6c9fc4fbd1b32c5c6c35 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 8 Nov 2018 14:02:00 -0800 Subject: [PATCH 4/5] Minor edits for clarity. Signed-off-by: Michael Vincerra --- source/clear-linux/guides/telemetrics/telemetry-journal.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/clear-linux/guides/telemetrics/telemetry-journal.rst b/source/clear-linux/guides/telemetrics/telemetry-journal.rst index 424945c0..c0c4be80 100644 --- a/source/clear-linux/guides/telemetrics/telemetry-journal.rst +++ b/source/clear-linux/guides/telemetrics/telemetry-journal.rst @@ -5,7 +5,7 @@ telemctl journal The telemctl ``journal`` command gives you access to features and options of the telemetry journal to assist with system analytics and debug. The -:command:`sudo telemctl journal` has a number of options to help filter +:command:`telemctl journal` has a number of options to help filter records. Use :command:`-h` or :command:`--help` to view usage options. .. code-block:: bash @@ -33,7 +33,7 @@ To see the listing of records in the journal, run the command: This will produce output like the following: -.. list-table:: **Table 1. Using -V for Verbose output** +.. list-table:: **Table 1. Journal Output** :widths: 10 30 20 20 20 :header-rows: 1 From 75ba97561ef849567eafe88b0c4d7b2c5dc25b50 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 8 Nov 2018 14:10:45 -0800 Subject: [PATCH 5/5] Adds new title as telemetry-z-api to telemetrics for toctree. Signed-off-by: Michael Vincerra --- source/clear-linux/guides/telemetrics/telemetrics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/telemetrics/telemetrics.rst b/source/clear-linux/guides/telemetrics/telemetrics.rst index 0a4d1cea..9731471f 100644 --- a/source/clear-linux/guides/telemetrics/telemetrics.rst +++ b/source/clear-linux/guides/telemetrics/telemetrics.rst @@ -16,4 +16,4 @@ telemetry backend solution. For more details, learn how to telemetry-config telemctl telemetry-journal - telemetry-api + telemetry-z-api