container_stats
Monitor Docker container performance by retrieving CPU, memory, and network statistics for running containers.
Instructions
Get CPU, memory, and network stats for a running Docker container.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name |
Implementation Reference
- src/docker.ts:136-179 (handler)The containerStats function is the core handler that executes the tool logic. It retrieves Docker container stats via dockerode, calculates CPU percentage from cpu_stats, computes memory usage/limit/percentage, and aggregates network RX/TX bytes across all interfaces, returning a formatted ContainerStats object.
export async function containerStats(id: string): Promise<ContainerStats> { const container = docker.getContainer(id); const stats = (await container.stats({ stream: false, })) as { cpu_stats: CpuStats; precpu_stats: CpuStats; memory_stats: MemoryStats; networks?: NetworkStats; }; const cpuStats = stats.cpu_stats; const precpuStats = stats.precpu_stats; const cpuDelta = cpuStats.cpu_usage.total_usage - precpuStats.cpu_usage.total_usage; const systemDelta = cpuStats.system_cpu_usage - precpuStats.system_cpu_usage; const cpuCount = cpuStats.cpu_usage.percpu_usage?.length ?? 1; const cpuPercent = systemDelta > 0 ? ((cpuDelta / systemDelta) * cpuCount * 100).toFixed(2) : "0.00"; const memUsage = stats.memory_stats.usage ?? 0; const memLimit = stats.memory_stats.limit ?? 0; const memPercent = memLimit > 0 ? ((memUsage / memLimit) * 100).toFixed(2) : "0.00"; const networks = stats.networks ?? {}; let rxBytes = 0; let txBytes = 0; for (const iface of Object.values(networks)) { rxBytes += iface.rx_bytes ?? 0; txBytes += iface.tx_bytes ?? 0; } return { cpu_percent: `${cpuPercent}%`, memory_usage: formatBytes(memUsage), memory_limit: formatBytes(memLimit), memory_percent: `${memPercent}%`, network_rx: formatBytes(rxBytes), network_tx: formatBytes(txBytes), }; } - src/docker.ts:15-22 (schema)The ContainerStats interface defines the output schema with typed fields: cpu_percent, memory_usage, memory_limit, memory_percent, network_rx, and network_tx (all strings with formatted values).
export interface ContainerStats { cpu_percent: string; memory_usage: string; memory_limit: string; memory_percent: string; network_rx: string; network_tx: string; } - src/index.ts:134-153 (registration)Registration of the 'container_stats' tool using server.tool() with a zod schema defining 'id' parameter (string, required). The handler calls containerStats(id) and formats the result into a human-readable text output showing CPU, memory, and network statistics.
server.tool( "container_stats", "Get CPU, memory, and network stats for a running Docker container.", { id: z.string().describe("Container ID or name") }, async ({ id }) => { const stats = await containerStats(id); return { content: [ { type: "text", text: [ `CPU: ${stats.cpu_percent}`, `Memory: ${stats.memory_usage} / ${stats.memory_limit} (${stats.memory_percent})`, `Network: ↓ ${stats.network_rx} ↑ ${stats.network_tx}`, ].join("\n"), }, ], }; }, );