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