Skip to content

Quick Start

Jump to bottom
zhenya edited this page Aug 8, 2025 · 19 revisions

Quick Start

This page provides a quick introduction to using Java System Monitor in your applications.

Basic Usage

System Information

Get basic system information using static methods:

import software.leonov.system.monitor.SystemMonitor;

// Get basic system information
int processors = SystemMonitor.getAvailableProcessors();
long availableMemory = SystemMonitor.getAvailableMemory();
String jvmName = SystemMonitor.getJVMName();
String jvmVendor = SystemMonitor.getJVMVendor();

System.out.println("Processors: " + processors);
System.out.println("Available memory: " + availableMemory + " bytes");
System.out.println("JVM: " + jvmName + " (" + jvmVendor + ")");

Lazy Monitoring

For applications that need periodic monitoring with minimal overhead:

import software.leonov.system.monitor.LazySystemMonitor;
import java.time.Duration;

// Create a lazy monitor with 1-second refresh threshold
try (SystemMonitor monitor = LazySystemMonitor.withRefreshThreshold(Duration.ofSeconds(1))) {
    
    // Get current metrics (will refresh if threshold elapsed)
    CpuUsage cpu = monitor.getCpuUsage();
    MemoryUsage memory = monitor.getMemoryUsage();
    
    System.out.println("Process CPU: " + cpu.getProcessCpuLoad() + "%");
    System.out.println("System CPU: " + cpu.getSystemCpuLoad() + "%");
    System.out.println("Used memory: " + memory.getUsedMemory() + " bytes");
    
    // Subsequent calls within 1 second will return cached values
    CpuUsage cachedCpu = monitor.getCpuUsage();
    // Same object reference due to caching
    assert cpu == cachedCpu;
}

Background Monitoring

For applications that need continuous monitoring in the background:

import software.leonov.system.monitor.BackgroundSystemMonitor;
import java.time.Duration;

// Create a background monitor that refreshes every 250ms
try (SystemMonitor monitor = BackgroundSystemMonitor
        .refreshEvery(Duration.ofMillis(250))
        .start()) {  // Don't forget to start() the monitor!
    
    // Background thread continuously refreshes metrics
    CpuUsage cpu = monitor.getCpuUsage();
    MemoryUsage memory = monitor.getMemoryUsage();
    
    System.out.println("Current CPU load: " + cpu.getSystemCpuLoad() + "%");
    System.out.println("Peak CPU load: " + cpu.getMaxSystemCpuLoad() + "%");
    System.out.println("Current memory: " + memory.getUsedMemory() + " bytes");
    System.out.println("Peak memory: " + memory.getMaxUsedMemory() + " bytes");
    
} // Automatically stops the background thread

Formatting Utilities

Use the Formatter class for human-readable output:

import static software.leonov.system.monitor.util.Formatter.*;

CpuUsage cpu = monitor.getCpuUsage();
MemoryUsage memory = monitor.getMemoryUsage();

// Format percentages
System.out.println("CPU: " + formatPercent(cpu.getSystemCpuLoad()));

// Format memory in binary units (1024-based)
System.out.println("Memory: " + formatBinaryBytes(memory.getUsedMemory()));

// Format memory in decimal units (1000-based)  
System.out.println("Memory: " + formatDecimalBytes(memory.getUsedMemory()));

Example output:

CPU: 23.5%
Memory: 512 MiB
Memory: 537 MB

Error Handling

The library uses -1 values to indicate unavailable metrics instead of throwing exceptions:

CpuUsage cpu = monitor.getCpuUsage();

if (cpu.getProcessCpuLoad() == -1.0) {
    System.out.println("Process CPU load not available on this platform");
} else {
    System.out.println("Process CPU: " + cpu.getProcessCpuLoad() + "%");
}

Thread Safety

All monitor implementations are thread-safe and can be used concurrently:

SystemMonitor monitor = BackgroundSystemMonitor.withDefaultRefreshInterval().start();

// Safe to call from multiple threads
CompletableFuture.runAsync(() -> {
    CpuUsage cpu = monitor.getCpuUsage();
    System.out.println("Thread 1 - CPU: " + cpu.getSystemCpuLoad() + "%");
});

CompletableFuture.runAsync(() -> {
    MemoryUsage memory = monitor.getMemoryUsage();
    System.out.println("Thread 2 - Memory: " + memory.getUsedMemory());
});

monitor.close();

Next Steps

Clone this wiki locally