MI measurement-specific declarations

Overview

// typedefs

typedef enum te_mi_meas_aggr te_mi_meas_aggr;
typedef enum te_mi_meas_type te_mi_meas_type;
typedef enum te_mi_meas_multiplier te_mi_meas_multiplier;
typedef struct te_mi_meas te_mi_meas;
typedef void enum te_mi_meas_view_type te_mi_meas_view_type;
typedef enum te_mi_graph_axis te_mi_graph_axis;

// enums

enum te_mi_graph_axis;
enum te_mi_meas_aggr;
enum te_mi_meas_multiplier;
enum te_mi_meas_type;
enum te_mi_meas_view_type;

// structs

struct te_mi_meas;

// global functions

te_errno te_mi_logger_meas_create(const char* tool, te_mi_logger** logger);
te_errno te_mi_log_meas(const char* tool, const te_mi_meas* measurements, const te_mi_log_kvpair* keys, const te_mi_log_kvpair* comments);
void te_mi_logger_add_meas(te_mi_logger* logger, te_errno* retval, te_mi_meas_type type, const char* name, te_mi_meas_aggr aggr, double val, te_mi_meas_multiplier multiplier);
void te_mi_logger_add_meas_obj(te_mi_logger* logger, te_errno* retval, const te_mi_meas* meas);
void te_mi_logger_add_meas_vec(te_mi_logger* logger, te_errno* retval, const te_mi_meas* measurements);
void te_mi_logger_add_meas_key(te_mi_logger* logger, te_errno* retval, const char* key, const char* value_fmt, ...);
void te_mi_logger_add_meas_view(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type type, const char* name, const char* title);
void te_mi_logger_meas_graph_axis_add(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type view_type, const char* view_name, te_mi_graph_axis axis, te_mi_meas_type meas_type, const char* meas_name);
static void te_mi_logger_meas_graph_axis_add_name(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type view_type, const char* view_name, te_mi_graph_axis axis, const char* meas_name);
static void te_mi_logger_meas_graph_axis_add_type(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type view_type, const char* view_name, te_mi_graph_axis axis, te_mi_meas_type meas_type);
void te_mi_logger_meas_point_add(te_mi_logger* logger, te_errno* retval, const char* view_name, te_mi_meas_type meas_type, const char* meas_name, te_mi_meas_aggr meas_aggr);

// macros

#define TE_MI_GRAPH_AUTO_SEQNO
#define TE_MI_MEAS(_type, _name, _aggr, _val, _multiplier)
#define TE_MI_MEAS_KEYS(...)
#define TE_MI_MEAS_V(...)

Detailed Documentation

Typedefs

typedef enum te_mi_meas_aggr te_mi_meas_aggr

Type of a measurement aggregation. The units of the measurement are defined by measurement type, unless different units are specified by aggregation explicilty.

First enum element must have value 0.

typedef enum te_mi_meas_type te_mi_meas_type

Type of a measurement. First enum element must have value 0.

typedef enum te_mi_meas_multiplier te_mi_meas_multiplier

Scale of a measurement result. The measurement value should be multiplied by this to get value in base units.

First enum element must have value 0.

typedef struct te_mi_meas te_mi_meas

Measurement. Base units of a measurement are defined by measurement type and measurement aggregation.

typedef void enum te_mi_meas_view_type te_mi_meas_view_type

Types of MI measurement views

typedef enum te_mi_graph_axis te_mi_graph_axis

Types of MI measurement view axis

Global Functions

te_errno te_mi_logger_meas_create(const char* tool, te_mi_logger** logger)

Create a MI measurements logger entity.

Parameters:

tool	Tool that was used for gathering measurements.
logger	Created logger

Returns:

Status code

te_errno te_mi_log_meas(const char* tool, const te_mi_meas* measurements, const te_mi_log_kvpair* keys, const te_mi_log_kvpair* comments)

Log MI measurements in one call. Logging steps:

create a logger;
add measurements, keys and comments to the logger;
log the MI data;
destroy the logger;

usage example:

te_mi_log_meas("mytool",
               TE_MI_MEAS_V(TE_MI_MEAS(PPS, "pps", MIN, 42.4, PLAIN),
                            TE_MI_MEAS(PPS, "pps", MEAN, 300, PLAIN),
                            TE_MI_MEAS(PPS, "pps", CV, 10, PLAIN),
                            TE_MI_MEAS(PPS, "pps", MAX, 5.4, KILO),
                            TE_MI_MEAS(TEMP, "mem", SINGLE, 42.4, PLAIN),
                            TE_MI_MEAS(LATENCY, "low", MEAN, 54, MICRO)),
               TE_MI_MEAS_KEYS({"key", "value"}),
               TE_MI_COMMENTS({"comment", "comment_value"}));

Parameters:

tool	Tool that was used for gathering measurements.
measurements	Measurements vector. The last element must have type `TE_MI_MEAS_END`.
keys	Measurement keys vector. The last element must have key `NULL`. May be `NULL` to not add any keys.
comments	Comments vector. The last element must have key `NULL`. May be `NULL` to not add any comments.

Returns:

Status code

void te_mi_logger_add_meas(te_mi_logger* logger, te_errno* retval, te_mi_meas_type type, const char* name, te_mi_meas_aggr aggr, double val, te_mi_meas_multiplier multiplier)

Add a measurement result to a MI logger. Results are aggregated by type - name pair. Multiple results with the the same type - name pair are allowed.

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().
type	The type of the measurement result
name	The name of the measurement result used to identify measurements in logs, may be `NULL`
aggr	Aggregation type of the measurement
val	Value of the measurement
multiplier	Scale of the measurement value

void te_mi_logger_add_meas_obj(te_mi_logger* logger, te_errno* retval, const te_mi_meas* meas)

Variation of te_mi_logger_add_result() function that accepts measurement as a struct.

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().
meas	Measurement

Returns:

Status code

void te_mi_logger_add_meas_vec(te_mi_logger* logger, te_errno* retval, const te_mi_meas* measurements)

Add an vector of measurements to a MI logger. Insertion stops on the first error (the rest of the measurements are not added and the successful insertions persist in 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().
measurements	Measurements vector. The last element must have type `TE_MI_MEAS_END`.

Returns:

Status code

void te_mi_logger_add_meas_key(te_mi_logger* logger, te_errno* retval, const char* key, const char* value_fmt, ...)

Add a measurement key to a MI logger. Measurement key is a key-value pair that represents extra measurement information.

Parameters:

logger	MI logger.
retval	Return code. If `NULL` is passed, `logger` is not `NULL` and error occurs, error flag is stored in `logger`, which will fail the next te_mi_logger_flush().
key	Measurement key
value_fmt	Format string for the value of the measurement key
…	Format string arguments

void te_mi_logger_add_meas_view(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type type, const char* name, const char* title)

Add a view for MI measurement.

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().
type	View type.
name	View name (must be unique for a given type; used for identifying a view when calling other functions of this API).
title	View title (may be an empty string; used as a title when displaying a graph).

void te_mi_logger_meas_graph_axis_add(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type view_type, const char* view_name, te_mi_graph_axis axis, te_mi_meas_type meas_type, const char* meas_name)

Add a measurement to a graph axis.

Parameters:

logger	MI logger.
retval	Return code. If `NULL` is passed, `logger` is not `NULL` and error occurs, error flag is stored in `logger`, which will fail the next te_mi_logger_flush().
view_type	View type.
view_name	Name of the graph view.
axis	Graph axis. For X axis only a single measurement may (and must) be specified - or a special `TE_MI_GRAPH_AUTO_SEQNO` keyword must be used as described below. Measurements specified for Y axis will each be drawn as a separate line. All measurements must have the same number of values as the measurement specified for X axis. If no measurement is specified for Y axis, it behaves as if all measurements are assigned to it except the one assigned to X axis.
meas_type	Measurement type. Using `TE_MI_MEAS_END` means that no type is specified; in that case measurement name must be unique (i.e. used only for a single type). Also `TE_MI_MEAS_END` can be used for `TE_MI_GRAPH_AUTO_SEQNO` (see `meas_name`).
meas_name	Name of the measurement. May be empty or `NULL` if `meas_type` is specified, in which case there should be the single parameter of a given type. For X axis `TE_MI_GRAPH_AUTO_SEQNO` can be used instead of a measurement name. In that case sequence number in array of values will be used as X-coordinate on a graph.

static void te_mi_logger_meas_graph_axis_add_name(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type view_type, const char* view_name, te_mi_graph_axis axis, const char* meas_name)

Wrapper for te_mi_logger_meas_graph_axis_add() which accepts only measurement name (which must be unique among all measurements of different types).

static void te_mi_logger_meas_graph_axis_add_type(te_mi_logger* logger, te_errno* retval, te_mi_meas_view_type view_type, const char* view_name, te_mi_graph_axis axis, te_mi_meas_type meas_type)

Wrapper for te_mi_logger_meas_graph_axis_add() which accepts only measurement type (there must be a single parameter with NULL name for a given type in such case).

void te_mi_logger_meas_point_add(te_mi_logger* logger, te_errno* retval, const char* view_name, te_mi_meas_type meas_type, const char* meas_name, te_mi_meas_aggr meas_aggr)

Add a point view representing MI measurement by a single point (mean, maximum value, etc). This view can be used for performance history graphs showing such ‘points’ taken from multiple logs on a single graph.

Example:

te_mi_logger *logger;

CHECK_RC(te_mi_logger_meas_create("mytool", &logger));
te_mi_logger_add_meas(logger, NULL, TE_MI_MEAS_LATENCY, "MeasName",
                      TE_MI_MEAS_AGGR_MEAN, 10,
                      TE_MI_MEAS_MULTIPLIER_NANO);

te_mi_logger_add_meas_view(logger, NULL, TE_MI_MEAS_VIEW_POINT, "ViewName",
                           "ViewTitile");
te_mi_logger_meas_point_add(logger, NULL, "ViewName", TE_MI_MEAS_LATENCY,
                             "MeasName", TE_MI_MEAS_AGGR_MEAN);

te_mi_logger_destroy(logger);

Parameters:

logger	MI logger.
retval	Return code. If `NULL` is passed, `logger` is not `NULL` and error occurs, error flag is stored in `logger`, which will fail the next te_mi_logger_flush().
view_name	Name of the point view.
meas_type	Measurement type. Using `TE_MI_MEAS_END` means that no type is specified; in that case measurement name must be unique (i.e. used only for a single type).
meas_name	Name of the measurement. May be empty or `NULL` if `meas_type` is specified, in which case there should be the single parameter of a given type.
meas_aggr	Type of a measurement aggregation. Using `TE_MI_MEAS_AGGR_SF_UNPECIFIED` means that aggr is not specified, in that case the measurement that is descibed by `meas_name` and `meas_type` must contain only one value.

Macros

#define TE_MI_GRAPH_AUTO_SEQNO

Special name meaning that sequence number should be used instead of values of some measurement on a given graph axis.

#define TE_MI_MEAS(_type, _name, _aggr, _val, _multiplier)

Convenience te_mi_meas constructor

#define TE_MI_MEAS_KEYS(...)

Convenience measurement key vector constructor for te_mi_log_meas()

#define TE_MI_MEAS_V(...)

Convenience te_mi_meas vector constructor for te_mi_log_meas()