File tirex_tracker.h

FileList > c > include > tirex_tracker.h

Go to the source code of this file

Contains tirex tracker's external C API.

• #include <stdbool.h>
• #include <stddef.h>
• #include <stdint.h>
• #include <tirex_tracker_export.h>

Classes

Type	Name
struct	tirexDataProvider_st Contains information about a data provider.
struct	tirexMeasureConf_st
struct	tirexMeasureInfo_st
struct	tirexResultEntry_st Holds a result entry, i.e., a key-value pair of a name (string) and a value (tirexResult).
struct	tirexTrackingConf_st Configures a tracking session: which measures to collect, which process (and optionally its descendants) to measure, and how often to poll.

Public Types

Type	Name
typedef void(*	tirexAbortCallback
typedef uint8_t	tirexAggregateFn
typedef struct tirexDataProvider_st	tirexDataProvider Contains information about a data provider.
typedef enum tirexError_enum	tirexError Categorizes different classes of error.
enum	tirexError_enum Categorizes different classes of error.
typedef void(*	tirexLogCallback Points to a function that takes in a log level, component, and message which should be logged.
typedef enum tirexLogLevel_enum	tirexLogLevel Represents different levels of verbosity.
enum	tirexLogLevel_enum Represents different levels of verbosity.
typedef enum tirexMeasure_enum	tirexMeasure Identifiers for all available measurements.
typedef struct tirexMeasureConf_st	tirexMeasureConf
typedef struct tirexMeasureHandle_st	tirexMeasureHandle Holds a handle to an ongoing measurement task.
typedef struct tirexMeasureInfo_st	tirexMeasureInfo
enum	tirexMeasure_enum Identifiers for all available measurements.
typedef struct tirexResult_st	tirexResult Holds a handle to the results of a measurement.
typedef struct tirexResultEntry_st	tirexResultEntry Holds a result entry, i.e., a key-value pair of a name (string) and a value (tirexResult).
typedef enum tirexResultType_enum	tirexResultType
enum	tirexResultType_enum
typedef struct tirexTrackingConf_st	tirexTrackingConf Configures a tracking session: which measures to collect, which process (and optionally its descendants) to measure, and how often to poll.

Public Static Attributes

Type	Name
const tirexMeasureConf	tirexNullConf = {.source = TIREX\_MEASURE\_INVALID} Represents an invalid measurement configuration.

Public Functions

Type	Name
TIREX_TRACKER_EXPORT size_t	tirexDataProviderGetAll (tirexDataProvider * providers, size_t bufsize) Populates the given buffer with all available providers (or at most bufsize ifbuf is not large enugh) and returns the total number of available providers.
TIREX_TRACKER_EXPORT tirexError	tirexFetchInfo (tirexTrackingConf conf, tirexResult ** result) Fetches the system information from the measures requested in conf , about the process identified byconf.pid (TIREX_PID_SELF, the default, for the calling process).
TIREX_TRACKER_EXPORT tirexError	tirexMeasureInfoGet (tirexMeasure measure, const tirexMeasureInfo ** info)
TIREX_TRACKER_EXPORT tirexError	tirexResultEntryGetByIndex (const tirexResult * result, size_t index, tirexResultEntry * entry)
TIREX_TRACKER_EXPORT tirexError	tirexResultEntryNum (const tirexResult * result, size_t * num) Returns the number of entries contained in the result set.
TIREX_TRACKER_EXPORT void	tirexResultFree (tirexResult * result) Deinitializes and frees the result pointed at by result .
TIREX_TRACKER_EXPORT void	tirexSetAbortCallback (tirexAbortCallback callback) Set a callback that should be used in case the program needs to abort.
TIREX_TRACKER_EXPORT void	tirexSetAbortLevel (tirexLogLevel level)
TIREX_TRACKER_EXPORT void	tirexSetLogCallback (tirexLogCallback callback) Set a callback that should be used for all future logs.
TIREX_TRACKER_EXPORT tirexError	tirexStartTracking (tirexTrackingConf conf, tirexMeasureHandle ** handle) Initializes the providers set in the configuration and starts measuring.
TIREX_TRACKER_EXPORT tirexError	tirexStopTracking (tirexMeasureHandle * handle, tirexResult ** result) Stops the measurement and deinitializes the data providers.

Macros

Type	Name
define	TIREX_AGG_MAX (1 << 2)
define	TIREX_AGG_MEAN (1 << 4)
define	TIREX_AGG_MIN (1 << 3)
define	TIREX_AGG_NO (1 << 1)
define	TIREX_PID_SELF ((int64\_t)0) Sentinel tirexTrackingConf::pid value meaning "track the calling process." This is the default: a zero-initialized tirexTrackingConf tracks the caller.
define	static_assert (cond, msg)

Public Types Documentation

typedef tirexAbortCallback

typedef void(* tirexAbortCallback) (const char *message);

---

typedef tirexAggregateFn

typedef uint8_t tirexAggregateFn;

---

typedef tirexDataProvider

Contains information about a data provider.

typedef struct tirexDataProvider_st tirexDataProvider;

Data providers are modules tasked with collecting associated metrics about the program.

---

typedef tirexError

Categorizes different classes of error.

typedef enum tirexError_enum tirexError;

---

enum tirexError_enum

Categorizes different classes of error.

enum tirexError_enum {
    TIREX_SUCCESS = 0,
    TIREX_INVALID_ARGUMENT = 1
};

---

typedef tirexLogCallback

Points to a function that takes in a log level, component, and message which should be logged.

typedef void(* tirexLogCallback) (tirexLogLevel level, const char *component, const char *message);

The log callback can handle the call as it likes (including ignoring it for example because logging is set to a lower verbosity or turned of). The component may be used to identify, where the log is comming from.

---

typedef tirexLogLevel

Represents different levels of verbosity.

typedef enum tirexLogLevel_enum tirexLogLevel;

The enum values are sorted by verbosity. That is, for example, if logs should only be logged level INFO or higher, then level >= INFO can be used to check what should be logged.

---

enum tirexLogLevel_enum

Represents different levels of verbosity.

enum tirexLogLevel_enum {
    TRACE,
    DEBUG,
    INFO,
    WARN,
    ERROR,
    CRITICAL
};

The enum values are sorted by verbosity. That is, for example, if logs should only be logged level INFO or higher, then level >= INFO can be used to check what should be logged.

---

typedef tirexMeasure

Identifiers for all available measurements.

typedef enum tirexMeasure_enum tirexMeasure;

Different types (EnvInfo, Time Series, Measure)

---

typedef tirexMeasureConf

typedef struct tirexMeasureConf_st tirexMeasureConf;

---

typedef tirexMeasureHandle

Holds a handle to an ongoing measurement task.

typedef struct tirexMeasureHandle_st tirexMeasureHandle;

---

typedef tirexMeasureInfo

typedef struct tirexMeasureInfo_st tirexMeasureInfo;

---

enum tirexMeasure_enum

Identifiers for all available measurements.

enum tirexMeasure_enum {
    TIREX_OS_NAME = 0,
    TIREX_OS_KERNEL = 1,
    TIREX_TIME_ELAPSED_WALL_CLOCK_MS = 2,
    TIREX_TIME_ELAPSED_USER_MS = 3,
    TIREX_TIME_ELAPSED_SYSTEM_MS = 4,
    TIREX_CPU_USED_PROCESS_PERCENT = 5,
    TIREX_CPU_USED_SYSTEM_PERCENT = 6,
    TIREX_CPU_AVAILABLE_SYSTEM_CORES = 7,
    TIREX_CPU_ENERGY_SYSTEM_JOULES = 8,
    TIREX_CPU_FEATURES = 9,
    TIREX_CPU_FREQUENCY_MHZ = 10,
    TIREX_CPU_FREQUENCY_MIN_MHZ = 11,
    TIREX_CPU_FREQUENCY_MAX_MHZ = 12,
    TIREX_CPU_VENDOR_ID = 13,
    TIREX_CPU_BYTE_ORDER = 14,
    TIREX_CPU_ARCHITECTURE = 15,
    TIREX_CPU_MODEL_NAME = 16,
    TIREX_CPU_CORES_PER_SOCKET = 17,
    TIREX_CPU_THREADS_PER_CORE = 18,
    TIREX_CPU_CACHES = 19,
    TIREX_CPU_VIRTUALIZATION = 20,
    TIREX_RAM_USED_PROCESS_KB = 21,
    TIREX_RAM_USED_SYSTEM_MB = 22,
    TIREX_RAM_AVAILABLE_SYSTEM_MB = 23,
    TIREX_RAM_ENERGY_SYSTEM_JOULES = 24,
    TIREX_GPU_SUPPORTED = 25,
    TIREX_GPU_MODEL_NAME = 26,
    TIREX_GPU_NUM_CORES = 27,
    TIREX_GPU_USED_PROCESS_PERCENT = 28,
    TIREX_GPU_USED_SYSTEM_PERCENT = 29,
    TIREX_GPU_VRAM_USED_PROCESS_MB = 30,
    TIREX_GPU_VRAM_USED_SYSTEM_MB = 31,
    TIREX_GPU_VRAM_AVAILABLE_SYSTEM_MB = 32,
    TIREX_GPU_ENERGY_SYSTEM_JOULES = 33,
    TIREX_GIT_IS_REPO = 34,
    TIREX_GIT_HASH = 35,
    TIREX_GIT_LAST_COMMIT_HASH = 36,
    TIREX_GIT_BRANCH = 37,
    TIREX_GIT_BRANCH_UPSTREAM = 38,
    TIREX_GIT_TAGS = 39,
    TIREX_GIT_REMOTE_ORIGIN = 40,
    TIREX_GIT_UNCOMMITTED_CHANGES = 41,
    TIREX_GIT_UNPUSHED_CHANGES = 42,
    TIREX_GIT_UNCHECKED_FILES = 43,
    TIREX_TIME_START = 44,
    TIREX_TIME_STOP = 45,
    TIREX_GIT_ROOT = 46,
    TIREX_GIT_ARCHIVE_PATH = 47,
    TIREX_VERSION_MEASURE = 48,
    TIREX_INVOCATION = 49,
    TIREX_DEVCONTAINER_CONF_PATHS = 50,
    TIREX_CPU_TEMPERATURE_CELSIUS = 51,
    TIREX_MEASURE_COUNT,
    TIREX_MEASURE_INVALID = -1
};

Different types (EnvInfo, Time Series, Measure)

---

typedef tirexResult

Holds a handle to the results of a measurement.

typedef struct tirexResult_st tirexResult;

The measurement result is structed as a tree of categories, subcategories and (at the leaves) values.

See also: tirexStopTracking(tirexMeasureHandle*, char**)

---

typedef tirexResultEntry

Holds a result entry, i.e., a key-value pair of a name (string) and a value (tirexResult).

typedef struct tirexResultEntry_st tirexResultEntry;

---

typedef tirexResultType

typedef enum tirexResultType_enum tirexResultType;

Note: Currently unused

---

enum tirexResultType_enum

enum tirexResultType_enum {
    TIREX_STRING = 0,
    TIREX_INTEGER = 1,
    TIREX_FLOATING = 2,
    TIREX_BOOLEAN = 3,
    TIREX_WSTRING = 4,
    TIREX_LIST = 1 << 7,
    TIREX_STRING_LIST = TIREX_STRING | TIREX_LIST,
    TIREX_INTEGER_LIST = TIREX_INTEGER | TIREX_LIST,
    TIREX_FLOATING_LIST = TIREX_FLOATING | TIREX_LIST,
    TIREX_BOOLEAN_LIST = TIREX_BOOLEAN | TIREX_LIST,
    TIREX_WSTRING_LIST = TIREX_WSTRING | TIREX_LIST
};

Note: Currently unused

---

typedef tirexTrackingConf

Configures a tracking session: which measures to collect, which process (and optionally its descendants) to measure, and how often to poll.

typedef struct tirexTrackingConf_st tirexTrackingConf;

For a minimal config, usetirexTrackingConf{.measures = ..., .pollIntervalMs = 100} to track the current process without its children.

---

Public Static Attributes Documentation

variable tirexNullConf

Represents an invalid measurement configuration.

const tirexMeasureConf tirexNullConf;

The null configuration should be used as a sentinel value to mark the end of the configuration in tirexStartTracking.

---

Public Functions Documentation

function tirexDataProviderGetAll

Populates the given buffer with all available providers (or at most bufsize ifbuf is not large enugh) and returns the total number of available providers.

TIREX_TRACKER_EXPORT size_t tirexDataProviderGetAll (
    tirexDataProvider * providers,
    size_t bufsize
) 

If buf is NULL , bufsize is ignored and only the number of available providers are returned. A typical call may look as follows:

size_t num = tirexDataProviderGetAll(NULL, 0);
struct tirexDataProvider* buf = (struct tirexDataProvider*)calloc(num, sizeof(struct tirexDataProvider));
tirexDataProviderGetAll(buf, num);
// ...
free(buf);

Parameters:

• providers
• bufsize

Returns:

The number of available data providers.

---

function tirexFetchInfo

Fetches the system information from the measures requested in conf , about the process identified byconf.pid (TIREX_PID_SELF, the default, for the calling process).

TIREX_TRACKER_EXPORT tirexError tirexFetchInfo (
    tirexTrackingConf conf,
    tirexResult ** result
) 

conf.pollIntervalMs is ignored, since this is a one-shot fetch rather than an ongoing tracking session. Some measures depend on which process is targeted (e.g., TIREX_INVOCATION and the git- and devcontainer-related measures are resolved relative to conf.pid 's working directory).

Parameters:

• conf
• result

Returns:

TIREX_SUCCESS on success or an error code.

---

function tirexMeasureInfoGet

TIREX_TRACKER_EXPORT tirexError tirexMeasureInfoGet (
    tirexMeasure measure,
    const tirexMeasureInfo ** info
) 

Parameters:

• measure
• info

Returns:

TIREX_SUCCESS on success or an error code.

---

function tirexResultEntryGetByIndex

TIREX_TRACKER_EXPORT tirexError tirexResultEntryGetByIndex (
    const tirexResult * result,
    size_t index,
    tirexResultEntry * entry
) 

Parameters:

• result
• index
• entry

Returns:

TIREX_SUCCESS on success or an error code.

---

function tirexResultEntryNum

Returns the number of entries contained in the result set.

TIREX_TRACKER_EXPORT tirexError tirexResultEntryNum (
    const tirexResult * result,
    size_t * num
) 

Parameters:

• result
• num

Returns:

TIREX_SUCCESS on success or an error code.

---

function tirexResultFree

Deinitializes and frees the result pointed at by result .

TIREX_TRACKER_EXPORT void tirexResultFree (
    tirexResult * result
) 

Parameters:

• result The result to be destructed.

---

function tirexSetAbortCallback

Set a callback that should be used in case the program needs to abort.

TIREX_TRACKER_EXPORT void tirexSetAbortCallback (
    tirexAbortCallback callback
) 

Per default, abort() is used.

Parameters:

• callback

---

function tirexSetAbortLevel

TIREX_TRACKER_EXPORT void tirexSetAbortLevel (
    tirexLogLevel level
) 

---

function tirexSetLogCallback

Set a callback that should be used for all future logs.

TIREX_TRACKER_EXPORT void tirexSetLogCallback (
    tirexLogCallback callback
) 

Per default, nothing is logged and passing NULL for callback disables logging.

Parameters:

• callback Points to a function that takes in a log level, component, and message which should be logged. Pass NULL to disable logging.

---

function tirexStartTracking

Initializes the providers set in the configuration and starts measuring.

TIREX_TRACKER_EXPORT tirexError tirexStartTracking (
    tirexTrackingConf conf,
    tirexMeasureHandle ** handle
) 

Parameters:

• conf configures the tracking behavior (which measures, which process, ...).
• handle a handle to the running measurement.

Returns:

TIREX_SUCCESS on success or an error code.

See also: tirexStopTracking

---

function tirexStopTracking

Stops the measurement and deinitializes the data providers.

TIREX_TRACKER_EXPORT tirexError tirexStopTracking (
    tirexMeasureHandle * handle,
    tirexResult ** result
) 

This function must be called exactly once for each measurement job.

Parameters:

• handle The handle of the running measurement that should be stopped.
• result a handle to the result tree of the measurement. Must be freed by the caller using tirexResultFree(tirexResult*)

Returns:

TIREX_SUCCESS on success or an error code.

See also: tirexStartTracking

---

Macro Definition Documentation

define TIREX_AGG_MAX

#define TIREX_AGG_MAX `(1 << 2)`

For each aggregation intervall, store the maximum value.

---

define TIREX_AGG_MEAN

#define TIREX_AGG_MEAN `(1 << 4)`

For each aggregation intervall, store the average value.

---

define TIREX_AGG_MIN

#define TIREX_AGG_MIN `(1 << 3)`

For each aggregation intervall, store the minimum value.

---

define TIREX_AGG_NO

#define TIREX_AGG_NO `(1 << 1)`

Perform no aggregation.

---

define TIREX_PID_SELF

Sentinel tirexTrackingConf::pid value meaning "track the calling process." This is the default: a zero-initialized tirexTrackingConf tracks the caller.

#define TIREX_PID_SELF `((int64_t)0)`

Safe as a sentinel since 0 is never a real process ID (reserved for kernel/scheduler bookkeeping on POSIX, and for the System Idle Process on Windows).

---

define static_assert

#define static_assert (
    cond,
    msg
) 

---

---

The documentation for this class was generated from the following file c/include/tirex_tracker.h