Skip to content

Java / Kotlin

Installation

The JVM library is published to Maven Central. It bundles a precompiled native library for Linux, macOS, and Windows — no separate install required.

Supported Java versions: 8, 11, 17, 21

dependencies {
    implementation("io.tira:tirex-tracker:x.x.x")
}

dependencies {
    implementation 'io.tira:tirex-tracker:x.x.x'
}

<dependency>
  <groupId>io.tira</groupId>
  <artifactId>tirex-tracker</artifactId>
  <version>x.x.x</version>
</dependency>

Replace x.x.x with the latest version tag.

GitHub Packages (alternative)

The library is also published to GitHub Packages. GitHub Packages requires authentication (Gradle instructions, Maven instructions).

Usage

Lambda block

import io.tira.tirex.tracker.*

fun main() {
    val result = track {
        // Your experiment code here
        trainModel()
    }
    println(result)
}

With specific measures

import io.tira.tirex.tracker.*

val result = track(
    measures = setOf(
        Measure.TIME_ELAPSED_WALL_CLOCK_MS,
        Measure.CPU_USED_PROCESS_PERCENT,
        Measure.RAM_USED_PROCESS_KB,
    ),
    pollIntervalMs = 100L
) {
    trainModel()
}

Lambda

import io.tira.tirex.tracker.*;
import java.util.Map;

Map<Measure, ResultEntry> result = Tracker.track(() -> {
    // Your experiment code here
    trainModel();
});
System.out.println(result);

Try-with-resources

TrackingHandle handle = TrackingHandle.start();
try (handle) {
    trainModel();
}
System.out.println(handle.getResults());

With specific measures

import java.util.Set;

var measures = Set.of(
    Measure.TIME_ELAPSED_WALL_CLOCK_MS,
    Measure.CPU_USED_PROCESS_PERCENT,
    Measure.RAM_USED_PROCESS_KB
);
var result = Tracker.track(measures, 100L, () -> trainModel());

Tracking a subprocess

By default, tracking targets the calling process. To track a different process instead (e.g. a spawned subprocess), pass its PID explicitly; setting trackSubprocesses additionally aggregates whatever that process itself goes on to spawn. See Tracked Measures for the per-platform RAM-accuracy caveats of tree-mode tracking.

Named arguments make pid and trackSubprocesses easy to reach directly:

val proc = ProcessBuilder("some-command").start()
val result = track(pid = proc.pid(), trackSubprocesses = true) {
    proc.waitFor()
}

pid and trackSubprocesses are the last two parameters of every overload. Since Java has no named arguments, reaching them means passing every optional parameter in between explicitly:

Process proc = new ProcessBuilder("some-command").start();
TrackingHandle handle = TrackingHandle.start(
    Tracker.getALL_MEASURES(), /*pollIntervalMillis=*/1000L,
    /*systemName=*/null, /*systemDescription=*/null,
    /*exportFilePath=*/null, /*exportFormat=*/null,
    /*pid=*/proc.pid(), /*trackSubprocesses=*/true
);
try (handle) {
    proc.waitFor();
}
System.out.println(handle.getResults());

Reading results

The result is a Map<Measure, ResultEntry>. Each ResultEntry has:

  • value — the measured value as a String
  • type — the ResultType (STRING, INTEGER, FLOATING, BOOLEAN, …)
val wallMs = result[Measure.TIME_ELAPSED_WALL_CLOCK_MS]?.value
println("Elapsed: $wallMs ms")

var wallMs = result.get(Measure.TIME_ELAPSED_WALL_CLOCK_MS).value();
System.out.println("Elapsed: " + wallMs + " ms");

Logging

import io.tira.tirex.tracker.*

setLogCallback { level, component, message ->
    println("[$level][$component] $message")
}

Tracker.setLogCallback((level, component, message) ->
    System.out.printf("[%s][%s] %s%n", level, component, message)
);

Java-specific measures

In addition to the platform measures tracked by the C core, the JVM wrapper collects:

Measure Description
JAVA_VERSION JVM version string
JAVA_VENDOR JVM vendor
JAVA_HOME JVM installation directory
JAVA_CLASS_PATH Java class path
JAVA_CLASS_VERSION Class file format version
JAVA_SPECIFICATION_VERSION Java specification version
JAVA_RUNTIME_VERSION Runtime version string
JAVA_VM_VERSION VM implementation version
JAVA_VM_VENDOR VM implementation vendor
JAVA_VM_NAME VM implementation name

API reference

Full Javadoc is available at javadoc.io/doc/io.tira/tirex-tracker.