doc/guides/howto/telemetry.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 DPDK Telemetry API User Guide
   5 ==============================
   6
   7 This document describes how the Data Plane Development Kit(DPDK) Telemetry API
   8 is used for querying port statistics from incoming traffic.
   9
  10 Introduction
  11 ------------
  12
  13 The ``librte_telemetry`` provides the functionality so that users may query
  14 metrics from incoming port traffic. The application which initializes packet
  15 forwarding will act as the server, sending metrics to the requesting application
  16 which acts as the client.
  17
  18 In DPDK, applications are used to initialize the ``telemetry``. To view incoming
  19 traffic on featured ports, the application should be run first (ie. after ports
  20 are configured). Once the application is running, the service assurance agent
  21 (for example the collectd plugin) should be run to begin querying the API.
  22
  23 A client connects their Service Assurance application to the DPDK application
  24 via a UNIX socket. Once a connection is established, a client can send JSON
  25 messages to the DPDK application requesting metrics via another UNIX client.
  26 This request is then handled and parsed if valid. The response is then
  27 formatted in JSON and sent back to the requesting client.
  28
  29 Pre-requisites
  30 ~~~~~~~~~~~~~~
  31
  32 * Python ≥ 2.5
  33
  34 * Jansson library for JSON serialization
  35
  36 Test Environment
  37 ----------------
  38
  39 ``telemetry`` offers a range of selftests that a client can run within
  40 the DPDK application.
  41
  42 Selftests are disabled by default. They can be enabled by setting the 'selftest'
  43 variable to 1 in rte_telemetry_initial_accept().
  44
  45 Note: this 'hardcoded' value is temporary.
  46
  47 Configuration
  48 -------------
  49
  50 Enable the telemetry API by modifying the following config option before
  51 building DPDK::
  52
  53         CONFIG_RTE_LIBRTE_TELEMETRY=y
  54
  55 Note: Meson will pick this up automatically if ``libjansson`` is available.
  56
  57 Running the Application
  58 -----------------------
  59
  60 The following steps demonstrate how to run the ``telemetry`` API  to query all
  61 statistics on all active ports, using the ``telemetry_client`` python script
  62 to query.
  63 Note: This guide assumes packet generation is applicable and the user is
  64 testing with testpmd as a DPDK primary application to forward packets, although
  65 any DPDK application is applicable.
  66
  67 #. Launch testpmd as the primary application with ``telemetry``.::
  68
  69         ./app/testpmd --telemetry
  70
  71 #. Launch the ``telemetry`` python script with a client filepath.::
  72
  73         python usertools/telemetry_client.py /var/run/some_client
  74
  75    The client filepath is going to be used to setup our UNIX connection with the
  76    DPDK primary application, in this case ``testpmd``
  77    This will initialize a menu where a client can proceed to recursively query
  78    statistics, request statistics once or unregister the file_path, thus exiting
  79    the menu.
  80
  81 #. Send traffic to any or all available ports from a traffic generator.
  82    Select a query option(recursive or singular polling).
  83    The metrics will then be displayed on the client terminal in JSON format.
  84
  85 #. Once finished, unregister the client using the menu command.