Docker Java API中getPercpuUsage()始终为null的原因排查

可能的原因 #

• Docker API版本不兼容：Docker daemon的API版本低于1.23时，不会返回percpu_usage字段，导致Java API映射后得到null。需确保Docker Java API的版本与宿主机Docker daemon的API版本匹配（可通过docker version查看Server端的API版本）。
• Java API实体类映射问题：部分版本的Docker Java API中，CpuUsage类的percpuUsage字段未正确映射Docker API返回的percpu_usage JSON字段，反序列化失败后返回null。
• 容器状态或环境限制：容器处于停止、暂停状态，或宿主机cgroup配置限制了统计数据收集，可能导致该字段为空。
• 首次获取统计数据：第一次调用容器stats接口时，preCpuStats会为空，但cpuStats中的percpuUsage仍应存在；若此时该字段为null，大概率是版本兼容问题。

解决建议 #

1. 版本匹配检查
   确认Docker Java API版本与Docker daemon API版本对应，例如Docker daemon 20.10.x对应API版本1.41，可选用docker-java:3.2.12版本。

2. 直接验证Docker API返回
   手动调用Docker原生API GET /containers/{containerId}/stats?stream=false，查看返回的JSON数据中是否存在cpu_stats.cpu_usage.percpu_usage字段：

   • 若不存在：说明Docker daemon不支持该字段，需升级Docker或更换计算方式。
   • 若存在：说明Java API映射有问题，更换兼容的docker-java版本即可。

3. 替代计算逻辑
   若无法获取percpuUsage，可通过宿主机CPU核心数替代其size()的作用，同时修正原计算逻辑的错误（原公式中cpuDelta - systemDelta应为除法）：

float cpuPercent = 0.0f;

Long totalUsageCurrent = stats.getCpuStats().getCpuUsage().getTotalUsage();
Long totalUsagePrevious = stats.getPreCpuStats().getCpuUsage().getTotalUsage();
Long systemUsageCurrent = stats.getCpuStats().getSystemCpuUsage();
Long systemUsagePrevious = stats.getPreCpuStats().getSystemCpuUsage();

if (totalUsageCurrent != null && totalUsagePrevious != null 
    && systemUsageCurrent != null && systemUsagePrevious != null) {
    float cpuDelta = totalUsageCurrent.floatValue() - totalUsagePrevious.floatValue();
    float systemDelta = systemUsageCurrent.floatValue() - systemUsagePrevious.floatValue();

    if (cpuDelta > 0.0 && systemDelta > 0.0) {
        // 用宿主机可用CPU核心数替代percpuUsage.size()
        int cpuCount = Runtime.getRuntime().availableProcessors();
        cpuPercent = (cpuDelta / systemDelta) * cpuCount * 100F;
    }
}

内容的提问来源于stack exchange，提问作者cohaa100