Renames telemetry-api.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
Michael Vincerra
2018-11-08 13:44:31 -08:00
parent 56f9440936
commit d5636371f6
@@ -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/