Skip to content

Quick Start

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

Quick Start

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

Usage Examples

System Information

Get basic system information using static methods:

out.printf("Available processors: %d%n",              SystemMonitor.getAvailableProcessors());
out.printf("Available memory: %d bytes%n",            SystemMonitor.getAvailableMemory());
out.printf("OS name: %s%n",                           SystemMonitor.getOperatingSystemName());
out.printf("OS version: %s%n",                        SystemMonitor.getOperatingSystemVersion());
out.printf("JVM name: %s%n",                          SystemMonitor.getJVMName());
out.printf("JVM vendor: %s%n",                        SystemMonitor.getJVMVendor());
out.printf("Supported Java version: %s%n",            SystemMonitor.getSupportedJavaVersion());
out.printf("Supported system-wide CPU metrics: %s%n", SystemMonitor.isSystemCpuUsageSupported());

Example output:

Available processors: 8
Available memory: 15246819328
OS name: Windows 10
OS version: 10.0
JVM name: Java HotSpot(TM) 64-Bit Server VM
JVM vendor: Oracle Corporation
Supported Java version: 1.8
Supported system-wide CPU metrics: true

Lazy Monitoring

LazySystemMonitor refreshes usage metrics on demand 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 (final SystemMonitor monitor = LazySystemMonitor.withRefreshThreshold(Duration.ofSeconds(1))) {
            
    // Get current metrics (will refresh on first call or if threshold elapsed)
    final CpuUsage cpu = monitor.getCpuUsage();
    final MemoryUsage memory = monitor.getMemoryUsage();

    out.printf("Process CPU: %.2f%%%n",   cpu.getProcessCpuLoad());
    out.printf("System CPU: %.2f%%%n",    cpu.getSystemCpuLoad());
    out.printf("Used memory: %d bytes%n", memory.getUsedMemory());
}

Background Monitoring

Background LazySystemMonitor refreshes usage metrics on demand applications that need periodic monitoring with minimal overhead:

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