app/testpmd: add flow table management
[dpdk.git] / doc / guides / prog_guide / telemetry_lib.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2020 Intel Corporation.
3
4 Telemetry Library
5 =================
6
7 The Telemetry library provides an interface to retrieve information from a
8 variety of DPDK libraries. The library provides this information via socket
9 connection, taking requests from a connected client and replying with the JSON
10 response containing the requested telemetry information.
11
12 Telemetry is enabled to run by default when running a DPDK application, and the
13 telemetry information from enabled libraries is made available. Libraries are
14 responsible for registering their own commands, and providing the callback
15 function that will format the library specific stats into the correct data
16 format, when requested.
17
18
19 Creating Callback Functions
20 ---------------------------
21
22
23 Function Type
24 ~~~~~~~~~~~~~
25
26 When creating a callback function in a library/app, it must be of the following type:
27
28 .. code-block:: c
29
30    typedef int (*telemetry_cb)(const char *cmd, const char *params,
31            struct rte_tel_data *info);
32
33 An example callback function is shown below:
34
35 .. code-block:: c
36
37    static int
38    handle_example_cmd(const char *cmd __rte_unused, const char *params __rte_unused,
39            struct rte_tel_data *d)
40
41 For more detail on the callback function parameters, please refer to the
42 `definition in the API doc
43 <https://doc.dpdk.org/api/rte__telemetry_8h.html#a41dc74d561442bb6184ee6dd1f9b5bcc>`_
44
45 **Example Callback**
46
47 This callback is an example of handling multiple commands in one callback,
48 and also shows the use of params which holds a port ID. The ``params`` input needs
49 to be validated and converted to the required integer type for port ID. The ``cmd``
50 parameter is then used in a comparison to decide which command was requested,
51 which will decide what port information should fill the ``rte_tel_data`` structure.
52
53 .. code-block:: c
54
55    int
56    handle_cmd_request(const char *cmd, const char *params,
57          struct rte_tel_data *d)
58    {
59       int port_id, used = 0;
60
61       if (params == NULL || strlen(params) == 0 || !isdigit(*params))
62          return -1;
63
64       port_id = atoi(params);
65       if (!rte_eth_dev_is_valid_port(port_id))
66          return -1;
67
68       if (strcmp(cmd, "/cmd_1") == 0)
69          /* Build up port data requested for command 1 */
70       else
71          /* Build up port data requested for command 2 */
72
73        return used;
74    }
75
76
77 Formatting Data
78 ~~~~~~~~~~~~~~~
79
80 The callback function provided by the library must format its telemetry
81 information in the required data format. The Telemetry library provides a data
82 utilities API to build up the data structure with the required information.
83 The telemetry library is then responsible for formatting the data structure
84 into a JSON response before sending to the client.
85
86
87 Array Data
88 ^^^^^^^^^^
89
90 Some data will need to be formatted in a list structure. For example, if a
91 callback needs to return five integer values in the data response, it can be
92 constructed using the following functions to build up the list:
93
94 .. code-block:: c
95
96    rte_tel_data_start_array(d, RTE_TEL_INT_VAL);
97        for(i = 0; i < 5; i++)
98            rte_tel_data_add_array_int(d, i);
99
100 The resulting response to the client shows the list data provided above
101 by the handler function in the library/app, placed in a JSON reply by telemetry::
102
103     {"/example_lib/five_ints": [0, 1, 2, 3, 4]}
104
105
106 Dictionary Data
107 ^^^^^^^^^^^^^^^
108
109 For data that needs to be structured in a dictionary with key/value pairs,
110 the data utilities API can also be used. For example, some information about
111 a brownie recipe is constructed in the callback function shown below:
112
113 .. code-block:: c
114
115    rte_tel_data_start_dict(d);
116    rte_tel_data_add_dict_string(d, "Recipe", "Brownies");
117    rte_tel_data_add_dict_int(d, "Prep time (mins)", 25);
118    rte_tel_data_add_dict_int(d, "Cooking time (mins)", 30);
119    rte_tel_data_add_dict_int(d, "Serves", 16);
120
121 The resulting response to the client shows the key/value data provided above
122 by the handler function in telemetry, placed in a JSON reply by telemetry::
123
124     {"/example_lib/brownie_recipe": {"Recipe": "Brownies", "Prep time (mins)": 25,
125       "Cooking time (mins)": 30, "Serves": 16}}
126
127
128 String Data
129 ^^^^^^^^^^^
130
131 Telemetry also supports single string data.
132 The data utilities API can again be used for this, see the example below.
133
134 .. code-block:: c
135
136    rte_tel_data_string(d, "This is an example string");
137
138 Giving the following response to the client::
139
140     {"/example_lib/string_example": "This is an example string"}
141
142 For more information on the range of data functions available in the API,
143 please refer to the `API doc <https://doc.dpdk.org/api/rte__telemetry_8h.html>`_
144
145
146 Registering Commands
147 --------------------
148
149 Libraries and applications must register commands to make their information
150 available via the Telemetry library. This involves providing a string command
151 in the required format ("/library/command"), the callback function that
152 will handle formatting the information when required, and help text for the
153 command. An example command being registered is shown below:
154
155 .. code-block:: c
156
157     rte_telemetry_register_cmd("/example_lib/string_example", handle_string,
158             "Returns an example string. Takes no parameters");
159
160
161 Using Commands
162 --------------
163
164 To use commands, with a DPDK app running (e.g. testpmd), use the
165 ``dpdk-telemetry.py`` script.
166 For details on its use, see the :doc:`../howto/telemetry`.