:orphan: .. index:: pair: group; Machine interface data logging .. _doxid-group__te__tools__te__mi__log: Machine interface 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. 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