rte_telemetry.h File Reference

#include <stdint.h>
#include <rte_compat.h>
#include <rte_common.h>

Go to the source code of this file.

Macros
#define	RTE_TEL_MAX_STRING_LEN   128
#define	RTE_TEL_MAX_SINGLE_STRING_LEN   8192
#define	RTE_TEL_MAX_DICT_ENTRIES   256
#define	RTE_TEL_MAX_ARRAY_ENTRIES   512

Typedefs
typedef int(*	telemetry_cb) (const char *cmd, const char *params, struct rte_tel_data *info)
typedef int(*	telemetry_arg_cb) (const char *cmd, const char *params, void *arg, struct rte_tel_data *info)
typedef void *(*	handler) (void *sock_id)

Enumerations
enum	rte_tel_value_type { , RTE_TEL_INT_VAL, RTE_TEL_UINT_VAL, RTE_TEL_CONTAINER }

Functions
int	rte_tel_data_start_array (struct rte_tel_data *d, enum rte_tel_value_type type)
int	rte_tel_data_start_dict (struct rte_tel_data *d)
int	rte_tel_data_string (struct rte_tel_data *d, const char *str)
int	rte_tel_data_add_array_string (struct rte_tel_data *d, const char *str)
int	rte_tel_data_add_array_int (struct rte_tel_data *d, int64_t x)
int	rte_tel_data_add_array_uint (struct rte_tel_data *d, uint64_t x)
int	rte_tel_data_add_array_u64 (struct rte_tel_data *d, uint64_t x) __rte_deprecated_msg("use 'rte_tel_data_add_array_uint' instead")
int	rte_tel_data_add_array_container (struct rte_tel_data *d, struct rte_tel_data *val, int keep)
__rte_experimental int	rte_tel_data_add_array_uint_hex (struct rte_tel_data *d, uint64_t val, uint8_t display_bitwidth)
int	rte_tel_data_add_dict_string (struct rte_tel_data *d, const char *name, const char *val)
int	rte_tel_data_add_dict_int (struct rte_tel_data *d, const char *name, int64_t val)
int	rte_tel_data_add_dict_uint (struct rte_tel_data *d, const char *name, uint64_t val)
int	rte_tel_data_add_dict_u64 (struct rte_tel_data *d, const char *name, uint64_t val) __rte_deprecated_msg("use 'rte_tel_data_add_dict_uint' instead")
int	rte_tel_data_add_dict_container (struct rte_tel_data *d, const char *name, struct rte_tel_data *val, int keep)
__rte_experimental int	rte_tel_data_add_dict_uint_hex (struct rte_tel_data *d, const char *name, uint64_t val, uint8_t display_bitwidth)
int	rte_telemetry_register_cmd (const char *cmd, telemetry_cb fn, const char *help)
__rte_experimental int	rte_telemetry_register_cmd_arg (const char *cmd, telemetry_arg_cb fn, void *arg, const char *help)
struct rte_tel_data *	rte_tel_data_alloc (void)

Detailed Description

RTE Telemetry.

The telemetry library provides a method to retrieve statistics from DPDK by sending a request message over a socket. DPDK will send a JSON encoded response containing telemetry data.

Definition in file rte_telemetry.h.

Macro Definition Documentation

RTE_TEL_MAX_STRING_LEN

#define RTE_TEL_MAX_STRING_LEN   128

Maximum length for string used in object.

Definition at line 17 of file rte_telemetry.h.

RTE_TEL_MAX_SINGLE_STRING_LEN

#define RTE_TEL_MAX_SINGLE_STRING_LEN   8192

Maximum length of string.

Definition at line 19 of file rte_telemetry.h.

RTE_TEL_MAX_DICT_ENTRIES

#define RTE_TEL_MAX_DICT_ENTRIES   256

Maximum number of dictionary entries.

Definition at line 21 of file rte_telemetry.h.

RTE_TEL_MAX_ARRAY_ENTRIES

#define RTE_TEL_MAX_ARRAY_ENTRIES   512

Maximum number of array entries.

Definition at line 23 of file rte_telemetry.h.

Typedef Documentation

telemetry_cb

typedef int(* telemetry_cb) (const char *cmd, const char *params, struct rte_tel_data *info)

This telemetry callback is used when registering a telemetry command. It handles getting and formatting information to be returned to telemetry when requested.

Parameters

cmd	The cmd that was requested by the client.
params	Contains data required by the callback function.
info	The information to be returned to the caller.

Returns

Length of buffer used on success.

Negative integer on error.

Definition at line 336 of file rte_telemetry.h.

telemetry_arg_cb

typedef int(* telemetry_arg_cb) (const char *cmd, const char *params, void *arg, struct rte_tel_data *info)

This telemetry callback is used when registering a telemetry command with rte_telemetry_register_cmd_arg().

It handles getting and formatting information to be returned to telemetry when requested.

Parameters

cmd	The cmd that was requested by the client.
params	Contains data required by the callback function.
arg	The opaque value that was passed to rte_telemetry_register_cmd_arg().
info	The information to be returned to the caller.

Returns

Length of buffer used on success.

Negative integer on error.

Definition at line 360 of file rte_telemetry.h.

handler

typedef void*(* handler) (void *sock_id)

Used for handling data received over a telemetry socket.

Parameters

sock_id

ID for the socket to be used by the handler.

Returns

Void.

Definition at line 372 of file rte_telemetry.h.

Enumeration Type Documentation

rte_tel_value_type

enum rte_tel_value_type

The types of data that can be managed in arrays or dicts. For arrays, this must be specified at creation time, while for dicts this is specified implicitly each time an element is added via calling a type-specific function.

Enumerator
RTE_TEL_INT_VAL	a string value
RTE_TEL_UINT_VAL	a signed 64-bit int value
RTE_TEL_CONTAINER	an unsigned 64-bit int value

Definition at line 44 of file rte_telemetry.h.

Function Documentation

rte_tel_data_start_array()

int rte_tel_data_start_array	(	struct rte_tel_data *	d,
		enum rte_tel_value_type	type
	)

Start an array of the specified type for returning from a callback

Parameters

d	The data structure passed to the callback
type	The type of the array of data

Returns

0 on success, negative errno on error

rte_tel_data_start_dict()

int rte_tel_data_start_dict

(

struct rte_tel_data *

d

)

Start a dictionary of values for returning from a callback

Dictionaries consist of key-values pairs to be returned, where the keys, or names, are strings and the values can be any of the types supported by telemetry. Name strings may only contain alphanumeric characters as well as '_' or '/'

Parameters

d	The data structure passed to the callback

Returns

0 on success, negative errno on error

Examples:

examples/ipsec-secgw/ipsec-secgw.c, and examples/l3fwd-power/main.c.

rte_tel_data_string()

int rte_tel_data_string	(	struct rte_tel_data *	d,
		const char *	str
	)

Set a string for returning from a callback

Parameters

d	The data structure passed to the callback
str	The string to be returned in the data structure

Returns

0 on success, negative errno on error, E2BIG on string truncation

rte_tel_data_add_array_string()

int rte_tel_data_add_array_string	(	struct rte_tel_data *	d,
		const char *	str
	)

Add a string to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_STRING_VAL as the type parameter.

Parameters

d	The data structure passed to the callback
str	The string to be returned in the array

Returns

0 on success, negative errno on error, E2BIG on string truncation

rte_tel_data_add_array_int()

int rte_tel_data_add_array_int	(	struct rte_tel_data *	d,
		int64_t	x
	)

Add an int to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_INT_VAL as the type parameter.

Parameters

d	The data structure passed to the callback
x	The number to be returned in the array

Returns

0 on success, negative errno on error

rte_tel_data_add_array_uint()

int rte_tel_data_add_array_uint	(	struct rte_tel_data *	d,
		uint64_t	x
	)

Add an unsigned value to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_UINT_VAL as the type parameter.

Parameters

d	The data structure passed to the callback
x	The number to be returned in the array

Returns

0 on success, negative errno on error

rte_tel_data_add_array_u64()

int rte_tel_data_add_array_u64	(	struct rte_tel_data *	d,
		uint64_t	x
	)

Add a uint64_t to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_UINT_VAL as the type parameter.

Parameters

d	The data structure passed to the callback
x	The number to be returned in the array

Returns

0 on success, negative errno on error

rte_tel_data_add_array_container()

int rte_tel_data_add_array_container	(	struct rte_tel_data *	d,
		struct rte_tel_data *	val,
		int	keep
	)

Add a container to an array. A container is an existing telemetry data array. The array the container is to be added to must have been started by rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter. The container type must be an array of type uint64_t/int/string.

Parameters

d	The data structure passed to the callback
val	The pointer to the container to be stored in the array.
keep	Flag to indicate that the container memory should not be automatically freed by the telemetry library once it has finished with the data. 1 = keep, 0 = free.

Returns

0 on success, negative errno on error

rte_tel_data_add_array_uint_hex()

__rte_experimental int rte_tel_data_add_array_uint_hex	(	struct rte_tel_data *	d,
		uint64_t	val,
		uint8_t	display_bitwidth
	)

Convert an unsigned integer to hexadecimal encoded strings and add this string to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_STRING_VAL as the type parameter.

Parameters

d	The data structure passed to the callback.
val	The number to be returned in the array as a hexadecimal encoded strings.
display_bitwidth	The display bit width of the 'val'. If 'display_bitwidth' is zero, the value is stored in the array as no-padding zero hexadecimal encoded string, or the value is stored as padding zero to specified hexadecimal width.

Returns

0 on success, negative errno on error.

rte_tel_data_add_dict_string()

int rte_tel_data_add_dict_string	(	struct rte_tel_data *	d,
		const char *	name,
		const char *	val
	)

Add a string value to a dictionary. The dict must have been started by rte_tel_data_start_dict().

Parameters

d	The data structure passed to the callback
name	The name the value is to be stored under in the dict Must contain only alphanumeric characters or the symbols: '_' or '/'
val	The string to be stored in the dict

Returns

0 on success, negative errno on error, E2BIG on string truncation of either name or value.

rte_tel_data_add_dict_int()

int rte_tel_data_add_dict_int	(	struct rte_tel_data *	d,
		const char *	name,
		int64_t	val
	)

Add an int value to a dictionary. The dict must have been started by rte_tel_data_start_dict().

Parameters

d	The data structure passed to the callback
name	The name the value is to be stored under in the dict Must contain only alphanumeric characters or the symbols: '_' or '/'
val	The number to be stored in the dict

Returns

0 on success, negative errno on error, E2BIG on string truncation of name.

rte_tel_data_add_dict_uint()

int rte_tel_data_add_dict_uint	(	struct rte_tel_data *	d,
		const char *	name,
		uint64_t	val
	)

Add an unsigned value to a dictionary. The dict must have been started by rte_tel_data_start_dict().

Parameters

d	The data structure passed to the callback
name	The name the value is to be stored under in the dict Must contain only alphanumeric characters or the symbols: '_' or '/'
val	The number to be stored in the dict

Returns

0 on success, negative errno on error, E2BIG on string truncation of name.

Examples:

examples/ipsec-secgw/ipsec-secgw.c, and examples/l3fwd-power/main.c.

rte_tel_data_add_dict_u64()

int rte_tel_data_add_dict_u64	(	struct rte_tel_data *	d,
		const char *	name,
		uint64_t	val
	)

Add a uint64_t value to a dictionary. The dict must have been started by rte_tel_data_start_dict().

Parameters

d	The data structure passed to the callback
name	The name the value is to be stored under in the dict Must contain only alphanumeric characters or the symbols: '_' or '/'
val	The number to be stored in the dict

Returns

0 on success, negative errno on error, E2BIG on string truncation of name.

rte_tel_data_add_dict_container()

int rte_tel_data_add_dict_container	(	struct rte_tel_data *	d,
		const char *	name,
		struct rte_tel_data *	val,
		int	keep
	)

Add a container to a dictionary. A container is an existing telemetry data array. The dict the container is to be added to must have been started by rte_tel_data_start_dict(). The container must be an array of type uint64_t/int/string.

Parameters

d	The data structure passed to the callback
name	The name the value is to be stored under in the dict. Must contain only alphanumeric characters or the symbols: '_' or '/'
val	The pointer to the container to be stored in the dict.
keep	Flag to indicate that the container memory should not be automatically freed by the telemetry library once it has finished with the data. 1 = keep, 0 = free.

Returns

0 on success, negative errno on error

Examples:

examples/ipsec-secgw/ipsec-secgw.c.

rte_tel_data_add_dict_uint_hex()

__rte_experimental int rte_tel_data_add_dict_uint_hex	(	struct rte_tel_data *	d,
		const char *	name,
		uint64_t	val,
		uint8_t	display_bitwidth
	)

Convert an unsigned integer to hexadecimal encoded strings and add this string to an dictionary. The dict must have been started by rte_tel_data_start_dict().

Parameters

d	The data structure passed to the callback.
name	The name of the value is to be stored in the dict. Must contain only alphanumeric characters or the symbols: '_' or '/'.
val	The number to be stored in the dict as a hexadecimal encoded strings.
display_bitwidth	The display bit width of the 'val'. If 'display_bitwidth' is zero, the value is stored in the array as no-padding zero hexadecimal encoded string, or the value is stored as padding zero to specified hexadecimal width.

Returns

0 on success, negative errno on error.

rte_telemetry_register_cmd()

int rte_telemetry_register_cmd	(	const char *	cmd,
		telemetry_cb	fn,
		const char *	help
	)

Used when registering a command and callback function with telemetry.

Parameters

cmd	The command to register with telemetry.
fn	Callback function to be called when the command is requested.
help	Help text for the command.

Returns

0 on success.

-EINVAL for invalid parameters failure.

-ENOMEM for mem allocation failure.

Examples:

examples/ipsec-secgw/ipsec-secgw.c, and examples/l3fwd-power/main.c.

rte_telemetry_register_cmd_arg()

__rte_experimental int rte_telemetry_register_cmd_arg	(	const char *	cmd,
		telemetry_arg_cb	fn,
		void *	arg,
		const char *	help
	)

Used when registering a command and callback function with telemetry.

Parameters

cmd	The command to register with telemetry.
fn	Callback function to be called when the command is requested.
arg	An opaque value that will be passed to the callback function.
help	Help text for the command.

Returns

0 on success.

-EINVAL for invalid parameters failure.

-ENOMEM for mem allocation failure.

rte_tel_data_alloc()

struct rte_tel_data* rte_tel_data_alloc

(

void

)

Get a pointer to a container with memory allocated. The container is to be used embedded within an existing telemetry dict/array.

Returns

Pointer to a container.

Examples:

examples/ipsec-secgw/ipsec-secgw.c.