From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by dpdk.org (Postfix) with ESMTP id E04784CE4 for ; Thu, 23 Aug 2018 14:08:37 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga104.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 23 Aug 2018 05:08:37 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,278,1531810800"; d="scan'208";a="256613884" Received: from silpixa00399503.ir.intel.com ([10.237.222.102]) by fmsmga005.fm.intel.com with ESMTP; 23 Aug 2018 05:08:36 -0700 From: Ciara Power To: harry.van.haaren@intel.com, brian.archbold@intel.com, emma.kenny@intel.com, ciara.power@intel.com Cc: dev@dpdk.org Date: Thu, 23 Aug 2018 13:08:11 +0100 Message-Id: <1535026093-101872-10-git-send-email-ciara.power@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1535026093-101872-1-git-send-email-ciara.power@intel.com> References: <1535026093-101872-1-git-send-email-ciara.power@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH 09/11] doc: add telemetry documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 23 Aug 2018 12:08:38 -0000 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. Signed-off-by: Ciara Power Signed-off-by: Brian Archbold --- doc/guides/howto/index.rst | 1 + doc/guides/howto/telemetry.rst | 86 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 doc/guides/howto/telemetry.rst 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..0a2ae97 --- /dev/null +++ b/doc/guides/howto/telemetry.rst @@ -0,0 +1,86 @@ +.. 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 can be used to initialize the ``telemetry`` as a virtual +device. 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. This is done by passing in an argument to the +virtual device initialization like so through the EAL command line.:: + + ./dpdk_app --vdev=telemetry,selftest=1 + + +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 the ``telemetry`` + virtual device.:: + + ./app/testpmd --vdev=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 connect 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. -- 2.7.4