From 6e9270eab112d68999a9124866dbfc46cd498d1b Mon Sep 17 00:00:00 2001 From: Ciara Power Date: Sat, 27 Oct 2018 10:17:48 +0100 Subject: [PATCH] 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 --- MAINTAINERS | 1 + doc/guides/howto/index.rst | 1 + doc/guides/howto/telemetry.rst | 85 ++++++++++++++++++++++++++ doc/guides/rel_notes/release_18_11.rst | 6 ++ 4 files changed, 93 insertions(+) create mode 100644 doc/guides/howto/telemetry.rst diff --git a/MAINTAINERS b/MAINTAINERS index 65441a9ef9..8d0ca103d4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1205,6 +1205,7 @@ Telemetry - EXPERIMENTAL M: Kevin Laatz F: lib/librte_telemetry/ F: usertools/dpdk-telemetry-client.py +F: doc/guides/howto/telemetry.rst BPF - EXPERIMENTAL M: Konstantin Ananyev diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst index e13a090c37..a642a2be13 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 0000000000..3fcb0619e2 --- /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. diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst index 07e1edf9fb..ae5c96fc2b 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 -- 2.20.1