Integrate Hutool OshiUtil with Spring Boot 3 for One‑Line System Monitoring

What is OshiUtil

OshiUtil is the Hutool wrapper around OSHI (Operating System and Hardware Information). It exposes static methods that internally use OSHI via JNA, so no native libraries are required.

It can retrieve CPU information (core count, model, real‑time usage), memory (total, used, available), operating system (name, version, architecture), JVM (Java version, runtime parameters), disk (model, capacity, partitions) and network (interface list, IP, MAC) data.

Why use OshiUtil instead of raw OSHI

Dependency : raw OSHI needs oshi-core; OshiUtil works with hutool-all (which also pulls oshi-core as a transitive dependency).

API complexity : OSHI requires manual query assembly; OshiUtil provides ready‑made static methods.

Learning curve : OSHI documentation must be consulted; OshiUtil methods are intuitive and can be used with a single look.

Feature scope : OSHI is very comprehensive (CPU, disk, processes, …); OshiUtil covers the common monitoring scenarios needed by most Java back‑ends.

Ecosystem fit : OSHI is standalone; OshiUtil can be mixed with other Hutool utilities.

Dependencies

<!-- Hutool utility library -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.41</version>
</dependency>

<!-- OSHI core library -->
<dependency>
    <groupId>com.github.oshi</groupId>
    <artifactId>oshi-core</artifactId>
    <version>6.4.1</version>
</dependency>

Both dependencies are required because OshiUtil is a thin wrapper around OSHI.

Basic usage examples

CPU information

import cn.hutool.system.oshi.CpuInfo;
import cn.hutool.system.oshi.OshiUtil;

public class TestOshi {
    public static void main(String[] args) {
        CpuInfo cpuInfo = OshiUtil.getCpuInfo();
        System.out.println("CPU cores: " + cpuInfo.getCpuNum());
        System.out.println("CPU usage: " + cpuInfo.getUsed() + "%");
        System.out.println("CPU idle: " + cpuInfo.getFree() + "%");
    }
}

Memory information

import oshi.hardware.GlobalMemory;
import cn.hutool.system.oshi.OshiUtil;

GlobalMemory memory = OshiUtil.getMemory();
long total = memory.getTotal();          // total bytes
long available = memory.getAvailable(); // available bytes
System.out.println("Total memory: " + (total / 1024 / 1024 / 1024) + " GB");
System.out.println("Available memory: " + (available / 1024 / 1024 / 1024) + " GB");

Operating system information

System.out.println("OS: " + OshiUtil.getOs().toString());

JVM information

import cn.hutool.system.SystemUtil;

var javaInfo = SystemUtil.getJavaInfo();
System.out.println("Java version: " + javaInfo.getVersion());
System.out.println("Java vendor: " + javaInfo.getVendor());

var runtimeInfo = SystemUtil.getRuntimeInfo();
System.out.println("JVM total memory: " + runtimeInfo.getTotalMemory() / 1024 / 1024 + " MB");
System.out.println("JVM free memory: " + runtimeInfo.getFreeMemory() / 1024 / 1024 + " MB");

Network information

OshiUtil.getNetworkIFs().forEach(net -> {
    System.out.println("Interface: " + net.getDisplayName());
    System.out.println("IP: " + java.util.Arrays.toString(net.getIPv4addr()));
    System.out.println("MAC: " + net.getMacaddr());
});

Spring Boot 3 integration

Service that aggregates system data

import cn.hutool.system.oshi.CpuInfo;
import cn.hutool.system.oshi.OshiUtil;
import org.springframework.stereotype.Service;
import java.util.HashMap;
import java.util.Map;

@Service
public class SystemMonitorService {
    public Map<String, Object> getSystemInfo() {
        Map<String, Object> result = new HashMap<>();
        CpuInfo cpuInfo = OshiUtil.getCpuInfo();
        result.put("cpuCores", cpuInfo.getCpuNum());
        result.put("cpuUsed", cpuInfo.getUsed() + "%");
        long totalMem = OshiUtil.getMemory().getTotal();
        long availMem = OshiUtil.getMemory().getAvailable();
        result.put("memoryTotal", String.format("%.2f GB", totalMem / 1024.0 / 1024.0 / 1024.0));
        result.put("memoryAvailable", String.format("%.2f GB", availMem / 1024.0 / 1024.0 / 1024.0));
        result.put("os", OshiUtil.getOs().toString());
        return result;
    }
}

REST controller exposing the data

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;

@RestController
public class SystemController {
    private final SystemMonitorService monitorService;
    public SystemController(SystemMonitorService monitorService) {
        this.monitorService = monitorService;
    }
    @GetMapping("/system/info")
    public Map<String, Object> getSystemInfo() {
        return monitorService.getSystemInfo();
    }
}

Accessing http://localhost:8080/system/info returns a JSON object with CPU, memory and OS details.

Typical use cases

Print system information at application startup for troubleshooting.

Provide a health‑check endpoint in microservices.

Display real‑time server status on an admin dashboard.

Important notes

CPU usage sampling delay : OshiUtil.getCpuInfo() blocks for about one second because it samples CPU usage twice. Use asynchronous calls or cache the result if response time is critical.

Windows load average : On Windows the system load average returns -1; monitor CPU usage directly instead.

Unit conversion : OSHI returns bytes for memory and disk. Convert to MB/GB manually or use FileUtil.readableFileSize() from Hutool.

Spring Boot 3 compatibility : Spring Boot 3 uses Jakarta EE. Use Hutool version 5.8.20 or newer. If a NoSuchMethodError occurs, explicitly set JNA version ≥ 5.13.0 in pom.xml.

Conclusion

OshiUtil offers a concise API over OSHI, allowing Java back‑end developers to obtain comprehensive system metrics with only a few lines of code. It is well suited for management consoles, monitoring services and any scenario where quick access to CPU, memory, OS, JVM, disk and network information is required.