Machine interface data logging

Overview

Definition of API for machine interface data logging. More…

// typedefs

typedef enum te_mi_type te_mi_type;
typedef struct te_mi_logger te_mi_logger;
typedef struct te_mi_log_kvpair te_mi_log_kvpair;

// enums

enum te_mi_type;

// structs

struct te_mi_log_kvpair;

// global functions

void te_mi_logger_add_comment(te_mi_logger* logger, te_errno* retval, const char* name, const char* value_fmt, ...);
void void te_mi_logger_reset(te_mi_logger* logger);
te_errno te_mi_logger_flush(te_mi_logger* logger);
void te_mi_logger_destroy(te_mi_logger* logger);

// macros

#define TE_MI_COMMENTS(...)
#define TE_MI_LOG_KVPAIRS(...)

Detailed Documentation

Definition of API for machine interface data logging.

Typedefs

typedef enum te_mi_type te_mi_type

Type of a MI data. First enum element must have value 0.

typedef struct te_mi_logger te_mi_logger

MI logger entity that is responsible for internally storing MI data, and logging it.

typedef struct 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.

te_kvpair is not used here since it is a tail queue element which is meant to be dynamically allocated. But te_mi_log_meas() API is more convenient to use with an on-stack allocated array argument, which can be easily constructed using te_mi_log_kvpair.

Global Functions

void te_mi_logger_add_comment(te_mi_logger* logger, te_errno* retval, const char* name, const char* value_fmt, ...)

Add a comment to a MI logger.

Parameters:

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 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

void void te_mi_logger_reset(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.

Parameters:

logger

MI logger

te_errno te_mi_logger_flush(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 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)” } }

Parameters:

logger	MI logger
TE_EFAIL	There were ignored internal logger failures

Returns:

Status code

void te_mi_logger_destroy(te_mi_logger* logger)

Flush (te_mi_logger_flush()) the MI data of a logger and free the logger itself.

Parameters:

logger

MI logger

Macros

#define TE_MI_COMMENTS(...)

Convenience comment vector constructor

#define TE_MI_LOG_KVPAIRS(...)

Convenience kvpair vector constructor