Design and Implementation of a Visual Monitoring System for Caffeine Cache

Caffeine is a high‑performance, memory‑optimized Java caching library derived from Google Guava Cache. It offers fast access, memory‑friendly sizing, multiple eviction policies, asynchronous loading, and rich statistics. Because of these features, many projects adopt Caffeine as the local cache solution, which creates a demand for real‑time monitoring and dynamic configuration.

The article describes a customized visual monitoring project built on top of Caffeine. The project provides the following capabilities:

Global management of cache instances across the whole application.

Visualization of per‑instance configuration, memory usage, and hit‑rate.

Real‑time data query, dynamic configuration updates, and cache entry invalidation.

Visualization Features

Global cache instance control panel showing instance name, size, expiration policy, memory usage, and hit‑rate.

Memory‑usage trend charts (last two days).

Hit‑rate trend charts (last two days).

Dynamic configuration changes (cache size and expiration time) for a single instance.

Cache data query supporting String, Long, and Integer keys.

Overall Architecture

The system consists of two parts: the project‑side (instrumented Caffeine library) and the control‑platform side (data collection, display, and configuration dispatch). Communication between the two sides supports both push (real‑time statistics) and pull (configuration updates and data queries).

Key extensions to the original Caffeine library include:

Memory‑usage estimation using ObjectSizeCalculator.getObjectSize .

Instance naming via .applyName("instanceName") and a global cacheInstanceMap for lookup.

Dynamic configuration APIs for maximum size, expiration after write/access, and refresh after write.

Cache data invalidation and inspection APIs.

Jetty‑based HTTP server for receiving commands and sending heart‑beat reports.

Code Snippets

static Cache<String, List<String>> accountWhiteCache = Caffeine.newBuilder()
            .expireAfterWrite(VivoConfigManager.getInteger("trade.account.white.list.cache.ttl", 10), TimeUnit.MINUTES)
            .recordStats().maximumSize(VivoConfigManager.getInteger("trade.account.white.list.cache.size", 100)).build();
// Conventional Caffeine instance creation

static Cache<String, List<String>> accountWhiteCache = Caffeine.newBuilder().applyName("accountWhiteCache")
            .expireAfterWrite(VivoConfigManager.getInteger("trade.account.white.list.cache.ttl", 10), TimeUnit.MINUTES)
            .recordStats().maximumSize(VivoConfigManager.getInteger("trade.account.white.list.cache.size", 100)).build();
// Instance creation with naming support

public final class Caffeine<K, V> {
    /** caffeine的实例名称 */
    String instanceName;
    /** caffeine的实例维护的Map信息 */
    static Map<String, Cache> cacheInstanceMap = new ConcurrentHashMap<>();
    @NonNull
    public <K1 extends K, V1 extends V> Cache<K1, V1> build() {
        // ... build logic ...
        if (null != localCache && StringUtils.isNotEmpty(localCache.getInstanceName())) {
            cacheInstanceMap.put(localCache.getInstanceName(), localCache);
        }
        return localCache;
    }
}

public static long getMemoryUsed() {
    // 预估内存占用
    return ObjectSizeCalculator.getObjectSize(data);
}

public static StatsData getCacheStats(String instanceName) {
    Cache cache = Caffeine.getCacheByInstanceName(instanceName);
    CacheStats cacheStats = cache.stats();
    StatsData statsData = new StatsData();
    statsData.setInstanceName(instanceName);
    statsData.setTimeStamp(System.currentTimeMillis()/1000);
    statsData.setMemoryUsed(String.valueOf(cache.getMemoryUsed()));
    // ... populate other fields ...
    return statsData;
}

The communication layer uses Jetty to expose HTTP endpoints ( /caffeine ) for configuration dispatch, cache inspection, and heartbeat reporting. The heartbeat periodically sends instance IP, port, and timestamp to aid in service health monitoring.

In summary, the project demonstrates how to extend Caffeine with naming, memory‑usage estimation, and real‑time monitoring features, and how to integrate these extensions into a visual management platform for operational insight.