path: root/doc
diff options
authorCiara Power <>2018-10-27 10:17:48 +0100
committerThomas Monjalon <>2018-10-27 15:21:38 +0200
commit6e9270eab112d68999a9124866dbfc46cd498d1b (patch)
tree599c6df36dfc988e9211b8ab4ffb44dfc75be67e /doc
parentd1b94da4a4e03e1f90a1980fecca9d430d54221e (diff)
doc: add telemetry how-to
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 a release notes update for telemetry. Signed-off-by: Ciara Power <> Signed-off-by: Brian Archbold <> Signed-off-by: Kevin Laatz <> Acked-by: Harry van Haaren <> Acked-by: Marko Kovacevic <>
Diffstat (limited to 'doc')
3 files changed, 92 insertions, 0 deletions
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
+ 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.
+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.
+* 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.
+Enable the telemetry API by modifying the following config option before
+building DPDK::
+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/ /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.
diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst
index 07e1edf..ae5c96f 100644
--- a/doc/guides/rel_notes/release_18_11.rst
+++ b/doc/guides/rel_notes/release_18_11.rst
@@ -254,6 +254,12 @@ New Features
to containers and host applications that need to have their cores frequency
controlled based on the rules contained in the policy.
+* **Added Telemetry API.**
+ Added the telemetry API which allows applications to transparently expose
+ their telemetry via a UNIX socket in JSON. The JSON can be consumed by any
+ Service Assurance agent, such as CollectD.
* **Added ability to switch queue deferred start flag on testpmd app.**
Added a console command to testpmd app, giving ability to switch