DPDK  20.05.0
Data Structures | Macros | Functions
rte_metrics.h File Reference
#include <stdint.h>
#include <rte_compat.h>

Go to the source code of this file.

Data Structures

struct  rte_metric_name
 
struct  rte_metric_value
 

Macros

#define RTE_METRICS_MAX_NAME_LEN   64
 
#define RTE_METRICS_GLOBAL   -1
 

Functions

void rte_metrics_init (int socket_id)
 
__rte_experimental 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 36 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.

Examples:
examples/l3fwd-power/main.c.

Definition at line 47 of file rte_metrics.h.

Function Documentation

void rte_metrics_init ( int  socket_id)

Initializes metric module. This function must be called from a primary process before metrics are used.

Parameters
socket_idSocket to use for shared memory allocation.
Examples:
examples/l3fwd-power/main.c.
__rte_experimental int rte_metrics_deinit ( void  )
Warning
EXPERIMENTAL: this API may change without prior notice

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
nameMetric 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
namesList of metric names
cnt_namesNumber 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
Examples:
examples/l3fwd-power/main.c.
int rte_metrics_get_names ( struct rte_metric_name names,
uint16_t  capacity 
)

Get metric name-key lookup table.

Parameters
namesA 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.
capacitySize (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_idPort id to query
valuesA 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.
capacitySize (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_idPort to update metrics for
keyId of metric to update
valueNew 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_idPort to update metrics for
keyBase id of metrics set to update
valuesSet of new values
countNumber of new values
Returns
  • -ERANGE if count exceeds metric set size
  • -EIO if unable to access shared metrics memory
  • Zero on success
Examples:
examples/l3fwd-power/main.c.