ESP Diagnostics Metrics¶

Metrics¶

Header File¶

components/esp_diagnostics/include/esp_diagnostics_metrics.h

Functions¶

esp_err_t esp_diag_metrics_init(esp_diag_metrics_config_t *config)¶

Initialize the diagnostics metrics.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] config: Pointer to a config structure of type esp_diag_metrics_config_t

esp_err_t esp_diag_metrics_deinit(void)¶

Deinitialize the diagnostics metrics.

Return: ESP_OK if successful, appropriate error code otherwise.

esp_err_t esp_diag_metrics_register(const char *tag, const char *key, const char *label, const char *path, esp_diag_data_type_t type)¶

Register a metrics.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Unique key for the metrics
[in] label: Label for the metrics
[in] path: Hierarchical path for key, must be separated by ‘.’ for more than one level
[in] type: Data type of metrics

esp_err_t esp_diag_metrics_unregister_all(void)¶

Unregister all previously registered metrics.

Return: ESP_OK if successful, qppropriate error code otherwise.

const esp_diag_metrics_meta_t *esp_diag_metrics_meta_get_all(uint32_t *len)¶

Get metadata for all metrics.

Return

array Array of metrics meta data

Parameters

[out] len: Length of the metrics meta data array

void esp_diag_metrics_meta_print_all(void)¶: Print metadata for all metrics.

esp_err_t esp_diag_metrics_unregister(const char *tag, const char *key)¶

Unregister a diagnostics metrics.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of the metrics
[in] key: Key for the metrics

esp_err_t esp_diag_metrics_add_unit(const char *tag, const char *key, const char *unit)¶

Specify unit of the data for the particular key.

Return

ESP_OK if successful, appropriate error code othewise.

Note

this API if used, should be called after esp_diag_metrics_register API with the same key to take effect

Parameters

[in] tag: Tag of the metrics
[in] key: Key for which the unit to be specified
[in] unit: Unit string of the data

esp_err_t esp_diag_metrics_report(esp_diag_data_type_t data_type, const char *tag, const char *key, const void *val, size_t val_sz, uint64_t ts)¶

Add metrics to storage.

Return

ESP_OK if successful, appropriate error code otherwise.

Note

esp_diag_timestamp_get() API can be used to get timestamp in mircoseconds.

Parameters

[in] data_type: Data type of metrics esp_diag_data_type_t
[in] tag: Tag of metrics
[in] key: Key of metrics
[in] val: Value of metrics
[in] val_sz: Size of val
[in] ts: Timestamp in microseconds, this should be the value at the time of data gathering

esp_err_t esp_diag_metrics_report_bool(const char *tag, const char *key, bool b)¶

Add the metrics of data type boolean.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Key of the metrics
[in] b: Value of the metrics

esp_err_t esp_diag_metrics_report_int(const char *tag, const char *key, int32_t i)¶

Add the metrics of data type integer.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Key of the metrics
[in] i: Value of the metrics

esp_err_t esp_diag_metrics_report_uint(const char *tag, const char *key, uint32_t u)¶

Add the metrics of data type unsigned integer.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Key of the metrics
[in] u: Value of the metrics

esp_err_t esp_diag_metrics_report_float(const char *tag, const char *key, float f)¶

Add the metrics of data type float.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Key of the metrics
[in] f: Value of the metrics

esp_err_t esp_diag_metrics_report_ipv4(const char *tag, const char *key, uint32_t ip)¶

Add the IPv4 address metrics.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Key of the metrics
[in] ip: IPv4 address

esp_err_t esp_diag_metrics_report_mac(const char *tag, const char *key, uint8_t *mac)¶

Add the MAC address metrics.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Key of the metrics
[in] mac: Array of length 6 i.e 6 octets of mac address

esp_err_t esp_diag_metrics_report_str(const char *tag, const char *key, const char *str)¶

Add the metrics of data type string.

Return

ESP_OK if successful, appropriate error code otherwise.

Parameters

[in] tag: Tag of metrics
[in] key: Key of the metrics
[in] str: Value of the metrics

Structures¶

struct esp_diag_metrics_config_t¶

Diagnostics metrics config structure.

Public Members

esp_diag_metrics_write_cb_t write_cb¶: Callback function to write diagnostics data

void *cb_arg¶: User data to pass in callback function

struct esp_diag_metrics_meta_t¶

Structure for diagnostics metrics metadata.

Public Members

const char *tag¶: Tag of metrics

const char *key¶: Unique key for the metrics

const char *label¶: Label for the metrics

const char *path¶: Hierarchical path for the key, must be separated by ‘.’ for more than one level, eg: “wifi”, “heap.internal”, “heap.external”

const char *unit¶: Data unit, can be NULL

esp_diag_data_type_t type¶: Data type of metrics

Type Definitions¶

typedef esp_err_t (*esp_diag_metrics_write_cb_t)(const char *tag, void *data, size_t len, void *cb_arg)¶

Callback to write metrics data.

Parameters

[in] tag: Tag for metrics
[in] data: Metrics data
[in] len: Length of metrics data
[in] cb_arg: User data to pass in write callback

System Metrics¶

Header File¶

components/esp_diagnostics/include/esp_diagnostics_system_metrics.h

Functions¶

esp_err_t esp_diag_heap_metrics_init(void)¶

Initialize the heap metrics.

Free heap, largest free block, and all time minimum free heap values are collected periodically. Parameters are collected for RAM in internal memory and external memory (if device has PSRAM).

The periodic interval is configurable through CONFIG_DIAG_HEAP_POLLING_INTERVAL Kconfig option. Default is 30 seconds and can be changed with esp_diag_heap_metrics_reset_interval() at runtime. Valid range is from 30 seconds to 24 hours (86400 seconds).

Return: ESP_OK if successful, appropriate error code otherwise.

esp_err_t esp_diag_heap_metrics_deinit(void)¶

Deinitialize the heap metrics.

Return: ESP_OK if successful, appropriate error code otherwise.

void esp_diag_heap_metrics_reset_interval(uint32_t period)¶

Reset the periodic interval.

By default, heap metrics are collected based on CONFIG_DIAG_HEAP_POLLING_INTERVAL Kconfig option. This function can be used to change the interval at runtime. If the interval is set to 0, heap metrics collection is disabled.

Parameters

[in] period: Period interval in seconds

esp_err_t esp_diag_heap_metrics_dump(void)¶

Dumps the heap metrics and prints them to the console.

This API collects and reports metrics value at any give point in time.

Return: ESP_OK if successful, appropriate error code otherwise.

esp_err_t esp_diag_wifi_metrics_init(void)¶

Initialize the wifi metrics.

Wi-Fi RSSI and minimum ever Wi-Fi RSSI values are collected periodically. The periodic interval is configurable through CONFIG_DIAG_WIFI_POLLING_INTERVAL Kconfig option. Default is 30 seconds and can be changed with esp_diag_wifi_metrics_reset_interval() at runtime. Valid range is from 30 seconds to 24 hours (86400 seconds).

Return: ESP_OK if successful, appropriate error code otherwise.

esp_err_t esp_diag_wifi_metrics_deinit(void)¶

Deinitialize the wifi metrics.

Return: ESP_OK if successful, appropriate error code otherwise.

esp_err_t esp_diag_wifi_metrics_dump(void)¶

Dumps the wifi metrics and prints them to the console.

This API can be used to collect wifi metrics at any given point in time.

Return: ESP_OK if successful, appropriate error code otherwise.

void esp_diag_wifi_metrics_reset_interval(uint32_t period)¶

Reset the periodic interval.

By default, wifi metrics are collected based on CONFIG_DIAG_WIFI_POLLING_INTERVAL Kconfig option. This function can be used to change the interval at runtime. If the interval is set to 0, wifi metrics collection is disabled.

Parameters

[in] period: Period interval in seconds