Skip to content

Java / Kotlin API Reference

Full Javadoc for the JVM library is hosted at:

javadoc.io/doc/io.tira/tirex-tracker

For installation and usage examples, see the Java / Kotlin getting started guide.

Quick reference

Kotlin

Function / Class Description
track(measures, pollIntervalMs, ..., pid, trackSubprocesses) { ... } Track a lambda block and return a result map.
tracking(measures, pollIntervalMs, ..., pid, trackSubprocesses) Returns a TrackingHandle for use with use { }.
startTracking(measures, pollIntervalMs, ..., pid, trackSubprocesses) Start tracking manually; returns a TrackingHandle.
stopTracking(handle) Stop tracking and return the result map.
fetchInfo(measures, pid, trackSubprocesses) Query static hardware/process info without tracking.
setLogCallback { level, component, message -> } Register a log callback.
providerInfos Returns a list of all available data providers.
measureInfos Returns a list of all available measures with metadata.

Java (Tracker class)

Method Description
Tracker.track(measures, pollIntervalMs, ..., pid, trackSubprocesses, callable) Track a Callable or lambda.
TrackingHandle.start(measures, pollIntervalMs, ..., pid, trackSubprocesses) Try-with-resources handle.
Tracker.startTracking(measures, pollIntervalMs, ..., pid, trackSubprocesses) Start tracking manually.
Tracker.stopTracking(handle) Stop tracking and return results.
Tracker.fetchInfo(measures, pid, trackSubprocesses) Query static hardware/process info.
Tracker.setLogCallback(callback) Register a log callback.
Tracker.getProviderInfos() List available data providers.
Tracker.getMeasureInfos() List available measures with metadata.

pid (default: the calling process) and trackSubprocesses (default: true) are the last two parameters of every overload above. In Kotlin, named arguments make them reachable directly (track(pid = proc.pid(), trackSubprocesses = true) { ... }); in Java, since there are no named arguments, reaching them means passing every optional parameter in between explicitly — see the getting started guide for a full example.

Key classes

Measure enum

All ~51 platform measures (matching the C API) plus Java-specific measures:

Measure.TIME_ELAPSED_WALL_CLOCK_MS
Measure.CPU_USED_PROCESS_PERCENT
Measure.RAM_USED_PROCESS_KB
Measure.GPU_ENERGY_SYSTEM_JOULES
Measure.GIT_HASH
// ...
Measure.JAVA_VERSION       // JVM-only
Measure.JAVA_VM_NAME       // JVM-only

ResultEntry data class

data class ResultEntry(
    val source: Measure,
    val value:  String,      // always a string; parse based on type
    val type:   ResultType,
)

Aggregation enum

Aggregation.NO    // full time series
Aggregation.MAX
Aggregation.MIN
Aggregation.MEAN

Aggregation values can be combined using the or infix operator in Kotlin: Aggregation.MAX or Aggregation.MEAN.

ProviderInfo data class

data class ProviderInfo(
    val name:        String,
    val description: String,
    val version:     String?,
)

MeasureInfo data class

data class MeasureInfo(
    val description: String,
    val dataType:    ResultType,
    val example:     String,
)

Export to IR Metadata

import io.tira.tirex.tracker.*

val info   = fetchInfo(allMeasures)
val result = track { runExperiment() }

exportIrMetadata(info, result, "ir_metadata.yml")

var info   = Tracker.fetchInfo(allMeasures);
var result = Tracker.track(() -> runExperiment());

Tracker.exportIrMetadata(info, result, "ir_metadata.yml");

See the IR Metadata guide for the output format.