--- name: "rte_metrics_get_names" 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_metrics.h" --- # rte\_metrics\_get\_names(3) Part of [rte\_metrics.h(3)](/rte_metrics.h/3.md). ## NAME rte\_metrics.h ## SYNOPSIS `#include `\ ### Data Structures struct **rte\_metric\_name**\ struct **rte\_metric\_value**\ ### Macros \#define **RTE\_METRICS\_MAX\_NAME\_LEN** 64\ \#define **RTE\_METRICS\_GLOBAL** -1\ ### Functions int **rte\_metrics\_init** (int socket\_id)\ int **rte\_metrics\_deinit** (void)\ int **rte\_metrics\_reg\_name** (const char \*name)\ int **rte\_metrics\_reg\_names** (const char \*const \*names, uint16\_t cnt\_names)\ int **rte\_metrics\_get\_names** (struct **rte\_metric\_name** \*names, uint16\_t capacity)\ int **rte\_metrics\_get\_values** (int port\_id, struct **rte\_metric\_value** \*values, uint16\_t capacity)\ int **rte\_metrics\_update\_value** (int port\_id, uint16\_t key, const uint64\_t value)\ int **rte\_metrics\_update\_values** (int port\_id, uint16\_t key, const uint64\_t \*values, uint32\_t count)\ ## Detailed Description DPDK Metrics module Metrics are statistics that are not generated by PMDs, and hence are better reported through a mechanism that is independent from the ethdev-based extended statistics. Providers will typically be other libraries and consumers will typically be applications. Metric information is populated using a push model, where producers update the values contained within the metric library by calling an update function on the relevant metrics. Consumers receive metric information by querying the central metric data, which is held in shared memory. Currently only bulk querying of metrics by consumers is supported. Definition in file **rte\_metrics.h**. ## Macro Definition Documentation ### #define RTE\_METRICS\_MAX\_NAME\_LEN 64 Maximum length of metric name (including null-terminator) Definition at line **35** of file **rte\_metrics.h**. ### #define RTE\_METRICS\_GLOBAL -1 Global metric special id. When used for the port\_id parameter when calling rte\_metrics\_update\_metric() or rte\_metrics\_update\_metric(), the global metric, which are not associated with any specific port (i.e. device), are updated. Definition at line **46** of file **rte\_metrics.h**. ## Function Documentation ### int rte\_metrics\_init (int socket\_id) Initializes metric module. This function must be called from a primary process before metrics are used. **Parameters** *socket\_id* Socket to use for shared memory allocation. **Returns** 0 on success Negative error code (from **rte\_errno.h**) on error: -EEXIST - a memzone for metrics already exists but metrics is not initialized -ENOMEM - cannot allocate metrics memzone -E\_RTE\_SECONDARY - function called from secondary process ### int rte\_metrics\_deinit (void) Deinitialize metric module. This function must be called from a primary process after all the metrics usage is over, to release the shared memory. **Returns** \-EINVAL - invalid parameter. -EIO: Error, unable to access metrics shared memory (**rte\_metrics\_init()** not called) 0 - success ### int rte\_metrics\_reg\_name (const char \* name) Register a metric, making it available as a reporting parameter. Registering a metric is the way producers declare a parameter that they wish to be reported. Once registered, the associated numeric key can be obtained via **rte\_metrics\_get\_names()**, which is required for updating said metric's value. **Parameters** *name* Metric name. If this exceeds RTE\_METRICS\_MAX\_NAME\_LEN (including the NULL terminator), it is truncated. **Returns** - • Zero or positive: Success (index key of new metric) - • \-EIO: Error, unable to access metrics shared memory (**rte\_metrics\_init()** not called) - • \-EINVAL: Error, invalid parameters - • \-ENOMEM: Error, maximum metrics reached ### int rte\_metrics\_reg\_names (const char \*const \* names, uint16\_t cnt\_names) Register a set of metrics. This is a bulk version of **rte\_metrics\_reg\_names()** and aside from handling multiple keys at once is functionally identical. **Parameters** *names* List of metric names\ *cnt\_names* Number of metrics in set **Returns** - • Zero or positive: Success (index key of start of set) - • \-EIO: Error, unable to access metrics shared memory (**rte\_metrics\_init()** not called) - • \-EINVAL: Error, invalid parameters - • \-ENOMEM: Error, maximum metrics reached ### int rte\_metrics\_get\_names (struct rte\_metric\_name \* names, uint16\_t capacity) Get metric name-key lookup table. **Parameters** *names* A struct **rte\_metric\_name** array of at least *capacity* in size to receive key names. If this is NULL, function returns the required number of elements for this array.\ *capacity* Size (number of elements) of struct **rte\_metric\_name** array. Disregarded if names is NULL. **Returns** - • Positive value above capacity: error, *names* is too small. Return value is required size. - • Positive value equal or less than capacity: Success. Return value is number of elements filled in. - • Negative value: error. ### int rte\_metrics\_get\_values (int port\_id, struct rte\_metric\_value \* values, uint16\_t capacity) Get metric value table. **Parameters** *port\_id* Port id to query\ *values* A struct **rte\_metric\_value** array of at least *capacity* in size to receive metric ids and values. If this is NULL, function returns the required number of elements for this array.\ *capacity* Size (number of elements) of struct **rte\_metric\_value** array. Disregarded if names is NULL. **Returns** - • Positive value above capacity: error, *values* is too small. Return value is required size. - • Positive value equal or less than capacity: Success. Return value is number of elements filled in. - • Negative value: error. ### int rte\_metrics\_update\_value (int port\_id, uint16\_t key, const uint64\_t value) Updates a metric **Parameters** *port\_id* Port to update metrics for \ *key* Id of metric to update \ *value* New value **Returns** - • \-EIO if unable to access shared metrics memory - • Zero on success ### int rte\_metrics\_update\_values (int port\_id, uint16\_t key, const uint64\_t \* values, uint32\_t count) Updates a metric set. Note that it is an error to try to update across a set boundary. **Parameters** *port\_id* Port to update metrics for \ *key* Base id of metrics set to update \ *values* Set of new values \ *count* Number of new values **Returns** - • \-ERANGE if count exceeds metric set size - • \-EIO if unable to access shared metrics memory - • Zero on success ## Author Generated automatically by Doxygen for DPDK from the source code.