Group measure

Modules > measure

Public Types

Type	Name
typedef uint8_t	tirexAggregateFn
typedef enum tirexMeasure_enum	tirexMeasure Identifiers for all available measurements.
typedef struct tirexMeasureHandle_st	tirexMeasureHandle Holds a handle to an ongoing measurement task.
enum	tirexMeasure_enum Identifiers for all available measurements.
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 Functions

Type	Name
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	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.

Public Types Documentation

typedef tirexAggregateFn

typedef uint8_t tirexAggregateFn;

---

typedef tirexMeasure

Identifiers for all available measurements.

typedef enum tirexMeasure_enum tirexMeasure;

Different types (EnvInfo, Time Series, Measure)

---

typedef tirexMeasureHandle

Holds a handle to an ongoing measurement task.

typedef struct tirexMeasureHandle_st tirexMeasureHandle;

---

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

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

---

---