rte_metrics.h(3)

📦
version 25.11.3 · 9 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_metrics.h 💖

okay bestie, welcome to rte_metrics.h — that's the header for the DPDK Metrics module, straight out of the Library Functions Manual. it's giving "statistics that live outside your PMDs" and honestly? iconic. let's get into it 🫶

✨ NAME ✨

rte_metrics.h — literally the whole file, that's the name, that's it 💅

🌸 SYNOPSIS 🌸

#include <stdint.h>

🎀 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 — say it with me 📣

So here's the tea ☕: metrics are statistics that are not generated by PMDs. which means they do NOT belong in the ethdev-based extended statistics situation — they get reported through their own independent mechanism instead. it's called having main character energy and refusing to be a side quest, periodt.

  • Providers will typically be other libraries.
  • Consumers will typically be applications.

how does the info get in there? push model, bestie. the producers update the values held in the metric library by calling an update function on the relevant metrics. no polling, no "hey can you refresh", they just push 🫡

how do consumers get it back out? they query the central metric data, and that data is held in shared memory. and rn — literally right now — only bulk querying of metrics by consumers is supported. that's the vibe check result, no cap.

📌 Definition in file rte_metrics.h.

💜 Macro Definition Documentation 💜

🌈 #define RTE_METRICS_MAX_NAME_LEN 64

Maximum length of metric name (including null-terminator). that's the cap, girl. 64 and don't push it 💀

📌 Definition at line 35 of file rte_metrics.h.

🌈 #define RTE_METRICS_GLOBAL -1

Global metric special id. it's the special little guy ✨

When you use it for the port_id parameter when calling rte_metrics_update_metric() or rte_metrics_update_metric(), the global metric gets updated — and global metrics are the ones not associated with any specific port (i.e. device). so no port, no device, just vibes and numbers.

📌 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. no sneaky secondary-process behavior, absolutely not.

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. Must be called from a primary process after all the metrics usage is over, so the shared memory actually gets released. clean up after yourself bestie, it's called closure 🧹✨

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 is literally how producers declare a parameter they wish to be reported. and once it's registered, the associated numeric key can be obtained via rte_metrics_get_names() — and bestie you need that key to update said metric's value. no key, no update, that's the rule 🔑

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. it's the bulk version, we love a bulk version 🧺

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. the whole little dictionary of who's who 📖

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. the actual numbers, the receipts 🧾

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. don't do it. seriously. the boundary is the 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. (it wrote itself, honestly kind of a slay 🤖💅)

okay that's the whole page bestie, you're officially literate in the DPDK Metrics module, go forth and push your metrics 🫶✨

this lil doc was brought to you by DPDK, Version 25.11.3, under the name rte_metrics.h(3) — mwah, bye 💖🎀🦋

📦 where this page comes from