1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation
6 #include <rte_compat.h>
8 #ifndef _RTE_TELEMETRY_H_
9 #define _RTE_TELEMETRY_H_
11 /** Maximum number of telemetry callbacks. */
12 #define TELEMETRY_MAX_CALLBACKS 64
13 /** Maximum length for string used in object. */
14 #define RTE_TEL_MAX_STRING_LEN 64
15 /** Maximum length of string. */
16 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
17 /** Maximum number of dictionary entries. */
18 #define RTE_TEL_MAX_DICT_ENTRIES 256
19 /** Maximum number of array entries. */
20 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
29 * All functions in this file may be changed or removed without prior notice.
31 * The telemetry library provides a method to retrieve statistics from
32 * DPDK by sending a request message over a socket. DPDK will send
33 * a JSON encoded response containing telemetry data.
36 /** opaque structure used internally for managing data from callbacks */
40 * The types of data that can be managed in arrays or dicts.
41 * For arrays, this must be specified at creation time, while for
42 * dicts this is specified implicitly each time an element is added
43 * via calling a type-specific function.
45 enum rte_tel_value_type {
46 RTE_TEL_STRING_VAL, /** a string value */
47 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
48 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
52 * Start an array of the specified type for returning from a callback
55 * The data structure passed to the callback
57 * The type of the array of data
59 * 0 on success, negative errno on error
63 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
66 * Start a dictionary of values for returning from a callback
69 * The data structure passed to the callback
71 * 0 on success, negative errno on error
75 rte_tel_data_start_dict(struct rte_tel_data *d);
78 * Set a string for returning from a callback
81 * The data structure passed to the callback
83 * The string to be returned in the data structure
85 * 0 on success, negative errno on error, E2BIG on string truncation
89 rte_tel_data_string(struct rte_tel_data *d, const char *str);
92 * Add a string to an array.
93 * The array must have been started by rte_tel_data_start_array() with
94 * RTE_TEL_STRING_VAL as the type parameter.
97 * The data structure passed to the callback
99 * The string to be returned in the array
101 * 0 on success, negative errno on error, E2BIG on string truncation
105 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
108 * Add an int to an array.
109 * The array must have been started by rte_tel_data_start_array() with
110 * RTE_TEL_INT_VAL as the type parameter.
113 * The data structure passed to the callback
115 * The number to be returned in the array
117 * 0 on success, negative errno on error
121 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
124 * Add a uint64_t to an array.
125 * The array must have been started by rte_tel_data_start_array() with
126 * RTE_TEL_U64_VAL as the type parameter.
129 * The data structure passed to the callback
131 * The number to be returned in the array
133 * 0 on success, negative errno on error
137 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
140 * Add a string value to a dictionary.
141 * The dict must have been started by rte_tel_data_start_dict().
144 * The data structure passed to the callback
146 * The name the value is to be stored under in the dict
148 * The string to be stored in the dict
150 * 0 on success, negative errno on error, E2BIG on string truncation of
151 * either name or value.
155 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
159 * Add an int value to a dictionary.
160 * The dict must have been started by rte_tel_data_start_dict().
163 * The data structure passed to the callback
165 * The name the value is to be stored under in the dict
167 * The number to be stored in the dict
169 * 0 on success, negative errno on error, E2BIG on string truncation of name.
173 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
176 * Add a uint64_t value to a dictionary.
177 * The dict must have been started by rte_tel_data_start_dict().
180 * The data structure passed to the callback
182 * The name the value is to be stored under in the dict
184 * The number to be stored in the dict
186 * 0 on success, negative errno on error, E2BIG on string truncation of name.
190 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
191 const char *name, uint64_t val);
194 * This telemetry callback is used when registering a telemetry command.
195 * It handles getting and formatting information to be returned to telemetry
199 * The cmd that was requested by the client.
201 * Contains data required by the callback function.
203 * The information to be returned to the caller.
206 * Length of buffer used on success.
208 * Negative integer on error.
210 typedef int (*telemetry_cb)(const char *cmd, const char *params,
211 struct rte_tel_data *info);
214 * Used for handling data received over a telemetry socket.
217 * ID for the socket to be used by the handler.
222 typedef void * (*handler)(void *sock_id);
225 * Used when registering a command and callback function with telemetry.
228 * The command to register with telemetry.
230 * Callback function to be called when the command is requested.
232 * Help text for the command.
237 * -EINVAL for invalid parameters failure.
239 * -ENOENT if max callbacks limit has been reached.
243 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
247 * Initialize Telemetry.
250 * The runtime directory of DPDK.
252 * The CPU set to be used for setting the thread affinity.
254 * This err_str pointer should point to NULL on entry. In the case of an error
255 * or warning, it will be non-NULL on exit.
264 rte_telemetry_init(const char *runtime_dir, rte_cpuset_t *cpuset,
265 const char **err_str);