From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <harry.van.haaren@intel.com>
Received: from mga01.intel.com (mga01.intel.com [192.55.52.88])
by dpdk.org (Postfix) with ESMTP id 4485B5920
for <dev@dpdk.org>; Sat, 27 Oct 2018 02:00:26 +0200 (CEST)
X-Amp-Result: SKIPPED(no attachment in message)
X-Amp-File-Uploaded: False
Received: from orsmga001.jf.intel.com ([10.7.209.18])
by fmsmga101.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;
26 Oct 2018 17:00:25 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.54,429,1534834800"; d="scan'208";a="103042257"
Received: from silpixa00399779.ir.intel.com (HELO
silpixa00399779.ger.corp.intel.com) ([10.237.223.188])
by orsmga001.jf.intel.com with ESMTP; 26 Oct 2018 17:00:23 -0700
From: Harry van Haaren <harry.van.haaren@intel.com>
To: dev@dpdk.org
Cc: thomas@monjalon.net, bruce.richardson@intel.com,
stephen@networkplumber.org, gaetan.rivet@6wind.com, shreyansh.jain@nxp.com,
mattias.ronnblom@ericsson.com, Ciara Power <ciara.power@intel.com>,
Brian Archbold <brian.archbold@intel.com>,
Kevin Laatz <kevin.laatz@intel.com>
Date: Sat, 27 Oct 2018 00:59:31 +0100
Message-Id: <20181026235933.79779-11-harry.van.haaren@intel.com>
X-Mailer: git-send-email 2.17.1
In-Reply-To: <20181026235933.79779-1-harry.van.haaren@intel.com>
References: <20181024160311.85457-1-kevin.laatz@intel.com>
<20181026235933.79779-1-harry.van.haaren@intel.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Subject: [dpdk-dev] [PATCH v9 10/12] doc: add telemetry documentation
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Sat, 27 Oct 2018 00:00:27 -0000
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 and a release notes update 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>
Acked-by: Harry van Haaren <harry.van.haaren@intel.com>
Acked-by: Marko Kovacevic <marko.kovacevic@intel.com>
---
MAINTAINERS | 5 ++
doc/guides/howto/index.rst | 1 +
doc/guides/howto/telemetry.rst | 85 ++++++++++++++++++++++++++
doc/guides/rel_notes/release_18_11.rst | 6 ++
4 files changed, 97 insertions(+)
create mode 100644 doc/guides/howto/telemetry.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index 17ee5b9d3..be4ceb9b8 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1208,6 +1208,11 @@ F: test/bpf/
F: test/test/test_bpf.c
F: doc/guides/prog_guide/bpf_lib.rst
+Telemetry - EXPERIMENTAL
+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 e13a090c3..a642a2be1 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 000000000..3fcb0619e
--- /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 c6256939b..ed7994241 100644
--- a/doc/guides/rel_notes/release_18_11.rst
+++ b/doc/guides/rel_notes/release_18_11.rst
@@ -256,6 +256,12 @@ New Features
the specified port. The port must be stopped before the command call in order
to reconfigure queues.
+* **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.
+
* **Add a new sample for vDPA**
The vdpa sample application creates vhost-user sockets by using the
--
2.17.1