Split up cpuUtilization and memoryUtilization into host and limit relative parts

Author: luca-vogels

package.json

@@ -1,6 +1,6 @@
 {
   "name": "lup-docker",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "NodeJS library to interact with the Docker engine.",
   "main": "./lib/index",
   "types": "./lib/index.d.ts",

src/__tests__/Docker.test.ts

@@ -20,18 +20,17 @@ test('createContainer', async () => {
 */
 
 /*
-test('getContainerStats', async () => {
+test('getContainerStatsReader', async () => {
   const client = new DockerClient();
-  const response = await client.getContainerStats('postgresql', { stream: true });
-  if(response.success?.stream){
-    const stream = response.success.stream;
-    const reader = stream.getReader();
-    for(let i=0; i < 5; i++){
-      const { done, value: stats } = await reader.read();
-      if(done) break;
+  const response = await client.getContainerStatsReader('postgresql');
+  if (response.success) {
+    const reader = response.success;
+    for (let i = 0; i < 5; i++) {
+      const stats = await reader.next();
+      if (!stats) break;
       console.log(JSON.stringify(stats, null, 2));
     }
-    await reader.cancel();
+    await reader.close();
   }
 });
 */

src/client.ts

@@ -32,6 +32,7 @@ import {
   DockerExportImageOptions,
   DockerExportImagesOptions,
   DockerContainerStats,
+  DockerContainerDetails,
 } from './types';
 import { DockerStatsStream, DockerLogStream, DockerStatsStreamReader } from './stream';
 import {
@@ -635,8 +636,10 @@ class DockerClient {
         }
 
         // stats object
+        const hostConfig =
+          (options?.hostConfig as DockerContainerDetails)?.hostConfig || options?.hostConfig || undefined;
         return {
-          success: decodeDockerContainerStats(JSON.parse((response as DockerRequestResultBody).body!))!,
+          success: decodeDockerContainerStats(JSON.parse((response as DockerRequestResultBody).body!), hostConfig)!,
         };
       },
     );

src/convert.ts

@@ -12,12 +12,14 @@ import {
   DockerContainerStorageStats,
   DockerCreateContainerOptions,
   DockerCredentials,
+  DockerHostConfig,
   DockerIdentityToken,
   DockerImage,
   DockerImageManifestSummary,
   DockerOCIDescriptor,
   DockerOCIPlatform,
 } from './types';
+import os from 'os';
 
 export function encodeCreateContainerOptions(image: string, options?: DockerCreateContainerOptions): string {
   const body: any = {};
@@ -553,21 +555,40 @@ export function decodeDockerContainerNetworkStats(json: any | undefined): Docker
   };
 }
 
-export function decodeDockerContainerStats(json: any | undefined): DockerContainerStats | undefined {
+export function decodeDockerContainerStats(
+  json: any | undefined,
+  hostConfig?: DockerHostConfig,
+): DockerContainerStats | undefined {
   if (!json) return undefined;
 
   const cpuStats = decodeDockerContainerCpuStats(json.cpu_stats);
   const preStats = decodeDockerContainerCpuStats(json.precpu_stats);
   const memoryStats = decodeDockerContainerMemoryStats(json.memory_stats);
 
+  const hostCpuCoreCount = os.cpus().length;
+  const hostMemoryTotal = os.totalmem();
+
   const cpuCoreCount = Math.max(cpuStats?.cpuUsage?.perCpuUsage?.length || 0, cpuStats?.onlineCpus || 0);
   const cpuDelta = Math.max(0, (cpuStats?.cpuUsage?.totalUsage || 0) - (preStats?.cpuUsage?.totalUsage || 0));
   const memoryTotal = memoryStats?.total;
   const memoryUsed = memoryStats?.usage ? Math.max(0, memoryStats?.usage - (memoryStats?.stats.cache || 0)) : undefined;
   const systemCpuDelta = Math.max(0, (cpuStats?.systemCpuUsage || 0) - (preStats?.systemCpuUsage || 0));
 
-  const cpuUtilization = systemCpuDelta > 0 ? (cpuDelta / systemCpuDelta) * Math.max(1, cpuCoreCount) : 0;
-  const memoryUtilization = memoryTotal && memoryUsed ? memoryUsed / memoryTotal : undefined;
+  let containerCpuLimit = hostCpuCoreCount; // default no limit
+  if (hostConfig?.nanoCpus && hostConfig?.cpuPeriod) {
+    containerCpuLimit = hostConfig.nanoCpus / 1e9;
+  } else if (hostConfig?.cpuQuota && hostConfig?.cpuPeriod) {
+    containerCpuLimit = hostConfig.cpuQuota / hostConfig.cpuPeriod;
+  } else if (hostConfig?.cpuCount) {
+    containerCpuLimit = hostConfig.cpuCount;
+  } else if (hostConfig?.cpuPercent) {
+    containerCpuLimit = (hostConfig.cpuPercent / 100.0) * hostCpuCoreCount;
+  }
+
+  const cpuUtilizationHost = systemCpuDelta > 0 ? cpuDelta / systemCpuDelta : 0;
+  const cpuUtilizationLimits = hostConfig ? (cpuUtilizationHost * containerCpuLimit) / hostCpuCoreCount : undefined;
+  const memoryUtilizationHost = memoryUsed !== undefined && hostMemoryTotal ? memoryUsed / hostMemoryTotal : undefined;
+  const memoryUtilizationLimits = memoryUsed !== undefined && memoryTotal ? memoryUsed / memoryTotal : undefined;
   const networkStats: { [networkInterface: string]: DockerContainerNetworkStats } = {};
 
   for (const [networkInterface, stats] of Object.entries<any>(json.networks || {})) {
@@ -606,11 +627,17 @@ export function decodeDockerContainerStats(json: any | undefined): DockerContain
     containerId: json.id || '',
     cpuCoreCount,
     cpuStats,
-    cpuUtilization,
+    cpuUtilization: {
+      host: cpuUtilizationHost,
+      limits: cpuUtilizationLimits,
+    },
     memoryStats: memoryStats!,
     memoryTotal,
     memoryUsed,
-    memoryUtilization,
+    memoryUtilization: {
+      host: memoryUtilizationHost,
+      limits: memoryUtilizationLimits,
+    },
     name: json.name,
     networkStats: json.networks ? networkStats : undefined,
     pidCount: json.pids_stats

src/types.ts

@@ -231,6 +231,13 @@ export type DockerContainerCpuStats = {
   };
 };
 
+export type DockerContainerDetails = {
+  /** Host configuration of the container. */
+  hostConfig: DockerHostConfig;
+
+  // TODO add more fields returned by the /containers/{id}/json endpoint ('Inspect container').
+};
+
 export type DockerContainerHealthState = 'starting' | 'healthy' | 'paused' | 'unhealthy';
 
 export type DockerContainerInheritedVolume = {
@@ -540,8 +547,23 @@ export type DockerContainerStats = {
   /** CPU related info of the container. */
   cpuStats?: DockerContainerCpuStats;
 
-  /** CPU utilization of the container in percentage 0.0-1.0. */
-  cpuUtilization?: number;
+  /** CPU utilization of the container in percentage (0.0-1.0). */
+  cpuUtilization: {
+    /**
+     * CPU utilization of the container in percentage 0.0-1.0 relative to the entire host CPU resources.
+     * If the container is limited in CPU resources this value will still be relative to the entire host CPU resources.
+     * e.g. if container is running on a 4-core host and is limited to 1-core (25%) the maximum value of this field will be 0.25 (25% of total host CPU).
+     */
+    host?: number;
+
+    /**
+     * CPU utilization of the container in percentage 0.0-1.0 relative to its assigned limits.
+     * If no limits are assigned this field will be identical to 'cpuUtilization'.
+     *
+     * @warning This field requires the 'hostConfig' option to be set when calling 'getContainerStats' to compute the correct value.
+     */
+    limits?: number;
+  };
 
   /**
    * Aggregates all memory stats since container inceptions on Linux.
@@ -555,8 +577,14 @@ export type DockerContainerStats = {
   /** Used memory in bytes. */
   memoryUsed?: number;
 
-  /** Memory utilization of the container in percentage 0.0-1.0. */
-  memoryUtilization?: number;
+  /** Memory utilization of the container in percentage (0.0-1.0). */
+  memoryUtilization: {
+    /** Memory utilization of the container in percentage 0.0-1.0 relative to the entire host memory. */
+    host?: number;
+
+    /** Memory utilization of the container in percentage 0.0-1.0 relative to its assigned limits. */
+    limits?: number;
+  };
 
   /** Name of the container. */
   name?: string;
@@ -903,6 +931,9 @@ export type DockerGetContainersOptions = {
 };
 
 export type DockerGetContainerStatsOptions = {
+  /** Needed if CPU and memory utilization should be computed relative to the limits applied to the container. */
+  hostConfig?: DockerContainerDetails | DockerHostConfig;
+
   /** Only get a single stat instead of waiting for 2 cycles. */
   oneShot?: boolean;
 };