mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-22 03:22:45 +00:00
Renames telemetry-api.
Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
@@ -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 <string>` 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:`<server>/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/
|
||||
Reference in New Issue
Block a user