:orphan: .. index:: pair: group; MI data logging .. _doxid-group__te__tools__te__mi__log: MI data logging =============== .. toctree:: :hidden: group_te_tools_te_mi_log_meas.rst enum_te_mi_type.rst struct_te_mi_log_kvpair.rst Overview ~~~~~~~~ Definition of API for machine interface data logging. :ref:`More...` | :ref:`MI measurement-specific declarations` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef enum :ref:`te_mi_type` :ref:`te_mi_type`; typedef struct :ref:`te_mi_logger` :ref:`te_mi_logger`; typedef struct :ref:`te_mi_log_kvpair` :ref:`te_mi_log_kvpair`; // enums enum :ref:`te_mi_type`; // structs struct :ref:`te_mi_log_kvpair`; // global functions void :ref:`te_mi_logger_add_comment`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const char* name, const char* value_fmt, ...); void void :ref:`te_mi_logger_reset`(:ref:`te_mi_logger`* logger); :ref:`te_errno` :ref:`te_mi_logger_flush`(:ref:`te_mi_logger`* logger); void :ref:`te_mi_logger_destroy`(:ref:`te_mi_logger`* logger); // macros #define :ref:`TE_MI_COMMENTS`(...) #define :ref:`TE_MI_LOG_KVPAIRS`(...) .. _details-group__te__tools__te__mi__log: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Definition of API for machine interface data logging. Copyright (C) 2019-2022 OKTET Labs Ltd. All rights reserved. Typedefs -------- .. index:: pair: typedef; te_mi_type .. _doxid-group__te__tools__te__mi__log_1ga56c6e1227e3237ba8957161ffb832de0: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`te_mi_type` te_mi_type Type of a MI data. First enum element must have value ``0``. .. index:: pair: typedef; te_mi_logger .. _doxid-group__te__tools__te__mi__log_1gaec19168a124d0845de6936405b58a4f5: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`te_mi_logger` te_mi_logger MI logger entity that is responsible for internally storing MI data, and logging it. .. index:: pair: typedef; te_mi_log_kvpair .. _doxid-group__te__tools__te__mi__log_1ga6fea31c5b72c43ae6335f5c3929a5658: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`te_mi_log_kvpair` te_mi_log_kvpair Key-value pair that represents a comment to any MI data. Comment is considered an additional MI data. The struct also used to represent a measurement key. ``:ref:`te_kvpair ``` is not used here since it is a tail queue element which is meant to be dynamically allocated. But :ref:`te_mi_log_meas() ` API is more convenient to use with an on-stack allocated array argument, which can be easily constructed using ``:ref:`te_mi_log_kvpair ```. Global Functions ---------------- .. index:: pair: function; te_mi_logger_add_comment .. _doxid-group__te__tools__te__mi__log_1gae7ba5cf7b4bcef630f7371e07269ee07: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_add_comment(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const char* name, const char* value_fmt, ...) Add a comment to a MI logger. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occures, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. TE_EEXIST means the name already exists. * - name - Name of the comment * - value_fmt - Format string for the value of the comment * - ... - Format string arguments .. index:: pair: function; te_mi_logger_reset .. _doxid-group__te__tools__te__mi__log_1gac790f37094eea93c562e9af1972a742c: .. ref-code-block:: cpp :class: doxyrest-title-code-block void void te_mi_logger_reset(:ref:`te_mi_logger`* logger) Purge the logger's MI data. The data is lost completely. The flag that indicates that previously called logger manipulation functions errors were ignored is cleared. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger .. index:: pair: function; te_mi_logger_flush .. _doxid-group__te__tools__te__mi__log_1ga141448758d66a1b9af9054579a50b9e1: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_mi_logger_flush(:ref:`te_mi_logger`* logger) * If there were any ignored logger internal failures - return an error. * Log the MI data of a logger as an ARTIFACT with deficated MI log level. * Remove the data from the logger (calls :ref:`te_mi_logger_reset() `). If the logger does not have any MI data, nothing is logged. Logger is ready to add new data after the call to the function. .. note:: The format of the MI log is JSON RFC 8259. The API passes the JSON string to logger without indentation. JSON-schema: see doc/drafts/mi-schema.json Example of a valid JSON: { "type":"measurement", "version":1, "tool":"testpmd", "results":[ { "type":"pps", "entries":[ { "aggr":"mean", "value":7040400.000, "base_units":"pps", "multiplier":"1" }, { "aggr":"cv", "value":0.000, "base_units":"", "multiplier":"1" } ] }, { "type":"throughput", "entries":[ { "aggr":"mean", "value":4731.149, "base_units":"bps", "multiplier":"1e+6" } ] }, { "type":"bandwidth-usage", "entries":[ { "aggr":"mean", "value":0.473, "base_units":"", "multiplier":"1" } ] } ], "keys":{ "Side":"Rx" }, "comments":{ "Stabilizaton":"reached on datapoint (+ leading zero datapoints): 10 (+ 1)" } } .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger * - TE_EFAIL - There were ignored internal logger failures .. rubric:: Returns: Status code .. index:: pair: function; te_mi_logger_destroy .. _doxid-group__te__tools__te__mi__log_1ga8c09a679779aedc5935f885277992074: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_destroy(:ref:`te_mi_logger`* logger) Flush (:ref:`te_mi_logger_flush() `) the MI data of a logger and free the logger itself. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger Macros ------ .. index:: pair: define; TE_MI_COMMENTS .. _doxid-group__te__tools__te__mi__log_1ga494ee8241c6c682309cf3a7de429d557: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_MI_COMMENTS(...) Convenience comment vector constructor .. index:: pair: define; TE_MI_LOG_KVPAIRS .. _doxid-group__te__tools__te__mi__log_1ga17b0e89c73065f91a1139cfafc5c554d: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_MI_LOG_KVPAIRS(...) Convenience kvpair vector constructor