---
name: "rte_telemetry.h"
section: "3"
platform: "linux"
package: "dpdk-doc"
version: "24.11.4-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rte_telemetry.h"
---

# rte\_telemetry.h(3)

## NAME

rte\_telemetry.h

## SYNOPSIS

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

### 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)\

### Enumerations

enum **rte\_tel\_value\_type** {  }\

### 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

### #define RTE\_TEL\_MAX\_STRING\_LEN 128

Maximum length for string used in object.

Definition at line **17** of file **rte\_telemetry.h**.

### #define RTE\_TEL\_MAX\_SINGLE\_STRING\_LEN 8192

Maximum length of string.

Definition at line **19** of file **rte\_telemetry.h**.

### #define RTE\_TEL\_MAX\_DICT\_ENTRIES 256

Maximum number of dictionary entries.

Definition at line **21** of file **rte\_telemetry.h**.

### #define RTE\_TEL\_MAX\_ARRAY\_ENTRIES 512

Maximum number of array entries.

Definition at line **23** of file **rte\_telemetry.h**.

## Typedef Documentation

### 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**.

### 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**.

## Enumeration Type Documentation

### 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

### 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*

### 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*

### 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*

### 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*

### 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*

### 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*

### 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*

### 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\_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.*

### 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.*

### 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.*

### 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.*

### 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.*

### 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*

### \_\_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.*

### 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.*

### \_\_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.*

### 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.*

## Author

*Generated automatically by Doxygen for DPDK from the source code.*