[v3,10/12] doc: add telemetry documentation

Message ID 20181010105134.48079-11-kevin.laatz@intel.com
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • introduce telemetry library
Related show

Checks

Context Check Description
ci/Intel-compilation fail Compilation issues
ci/checkpatch success coding style OK

Commit Message

Kevin Laatz Oct. 10, 2018, 10:51 a.m.
From: Ciara Power <ciara.power@intel.com>

This patch adds all documentation for telemetry.

A description on how to use the Telemetry API with a DPDK
application is given in this document.

It also adds the MAINTAINERS file entry for telemetry.

Signed-off-by: Ciara Power <ciara.power@intel.com>
Signed-off-by: Brian Archbold <brian.archbold@intel.com>
Signed-off-by: Kevin Laatz <kevin.laatz@intel.com>
---
 MAINTAINERS                    |  5 +++
 doc/guides/howto/index.rst     |  1 +
 doc/guides/howto/telemetry.rst | 85 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+)
 create mode 100644 doc/guides/howto/telemetry.rst

Patch

diff --git a/MAINTAINERS b/MAINTAINERS
index 84b9ff7..e695a68 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1168,6 +1168,11 @@  F: test/bpf/
 F: test/test/test_bpf.c
 F: doc/guides/prog_guide/bpf_lib.rst
 
+Telemetry
+M: Kevin Laatz <kevin.laatz@intel.com>
+F: lib/librte_telemetry/
+F: usertools/dpdk-telemetry-client.py
+F: doc/guides/howto/telemetry.rst
 
 Test Applications
 -----------------
diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst
index e13a090..a642a2b 100644
--- a/doc/guides/howto/index.rst
+++ b/doc/guides/howto/index.rst
@@ -17,3 +17,4 @@  HowTo Guides
     virtio_user_for_container_networking
     virtio_user_as_exceptional_path
     packet_capture_framework
+    telemetry
diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst
new file mode 100644
index 0000000..3fcb061
--- /dev/null
+++ b/doc/guides/howto/telemetry.rst
@@ -0,0 +1,85 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+DPDK Telemetry API User Guide
+==============================
+
+This document describes how the Data Plane Development Kit(DPDK) Telemetry API
+is used for querying port statistics from incoming traffic.
+
+Introduction
+------------
+
+The ``librte_telemetry`` provides the functionality so that users may query
+metrics from incoming port traffic. The application which initializes packet
+forwarding will act as the server, sending metrics to the requesting application
+which acts as the client.
+
+In DPDK, applications are used to initialize the ``telemetry``. To view incoming
+traffic on featured ports, the application should be run first (ie. after ports
+are configured). Once the application is running, the service assurance agent
+(for example the collectd plugin) should be run to begin querying the API.
+
+A client connects their Service Assurance application to the DPDK application
+via a UNIX socket. Once a connection is established, a client can send JSON
+messages to the DPDK application requesting metrics via another UNIX client.
+This request is then handled and parsed if valid. The response is then
+formatted in JSON and sent back to the requesting client.
+
+Pre-requisites
+~~~~~~~~~~~~~~
+
+* Python ≥ 2.5
+
+* Jansson library for JSON serialization
+
+Test Environment
+----------------
+
+``telemetry`` offers a range of selftests that a client can run within
+the DPDK application.
+
+Selftests are disabled by default. They can be enabled by setting the 'selftest'
+variable to 1 in rte_telemetry_initial_accept().
+
+Note: this 'hardcoded' value is temporary.
+
+Configuration
+-------------
+
+Enable the telemetry API by modifying the following config option before
+building DPDK::
+
+        CONFIG_RTE_LIBRTE_TELEMETRY=y
+
+Note: Meson will pick this up automatically if ``libjansson`` is available.
+
+Running the Application
+-----------------------
+
+The following steps demonstrate how to run the ``telemetry`` API  to query all
+statistics on all active ports, using the ``telemetry_client`` python script
+to query.
+Note: This guide assumes packet generation is applicable and the user is
+testing with testpmd as a DPDK primary application to forward packets, although
+any DPDK application is applicable.
+
+#. Launch testpmd as the primary application with ``telemetry``.::
+
+        ./app/testpmd --telemetry
+
+#. Launch the ``telemetry`` python script with a client filepath.::
+
+        python usertools/telemetry_client.py /var/run/some_client
+
+   The client filepath is going to be used to setup our UNIX connection with the
+   DPDK primary application, in this case ``testpmd``
+   This will initialize a menu where a client can proceed to recursively query
+   statistics, request statistics once or unregister the file_path, thus exiting
+   the menu.
+
+#. Send traffic to any or all available ports from a traffic generator.
+   Select a query option(recursive or singular polling).
+   The metrics will then be displayed on the client terminal in JSON format.
+
+#. Once finished, unregister the client using the menu command.