When to Use
- Resource monitoring: Poll container stats on a schedule and alert when CPU exceeds 85% or memory usage exceeds 80% of the configured limit.
- Metrics dashboard: Feed container resource data into a metrics aggregator or Slack/email status report at regular intervals.
- Runaway process detection: Detect containers consuming unexpectedly high CPU (e.g. >90% sustained for 5 minutes) and trigger an automatic restart workflow.
- Auto-scaling trigger: Trigger a scale-up workflow when memory consumption crosses a threshold, creating additional worker containers.
- I/O pattern analysis: Track block read/write patterns to identify storage bottlenecks and inform infrastructure sizing decisions.
This node retrieves a single-sample snapshot of container stats (non-streaming mode). CPU percentage is calculated from the delta between two internal counter readings taken at the moment of the API call. For sustained monitoring, call this node on a repeating schedule workflow rather than attempting to stream live data.
Configuration
Connection Fields
| Field | Type | Default | Description |
|---|
dockerHost | string | unix:///var/run/docker.sock | Docker socket path or TCP endpoint |
connectionType | string | unixsocket | unixsocket | tcp | tcptls |
tlsCertPath | string | — | TLS certificate directory. Required for tcptls. optional |
timeoutSeconds | int | 30 | Operation timeout. Stats collection may take 1-2 seconds for CPU delta calculation. optional |
Operation Fields
| Field | Type | Required | Description |
|---|
resource | string | required | Must be container |
operation | string | required | Must be stats |
ContainerId | string | required | Container ID or name. Container must be running. |
Sample Configuration
{
"resource": "container",
"operation": "stats",
"ContainerId": "api-service",
"connection": {
"dockerHost": "unix:///var/run/docker.sock",
"connectionType": "unixsocket",
"timeoutSeconds": 10
}
}
Validation Errors
| Error Code | Trigger | Resolution |
|---|
MISSING_INPUT | ContainerId is empty | Provide the container name or ID. |
NOT_FOUND | Container does not exist | Verify the container name. Use container/list to enumerate available containers. |
CONFLICT | Container is not running | Stats are only available for running containers. Check state with container/inspect first. |
DOCKER_API_ERROR | Daemon error retrieving stats | Check daemon logs. Can occur on very new containers before their cgroup metrics are initialized. |
Output
Success Port
| Field | Type | Description |
|---|
cpuPercent | number | CPU usage as a percentage (0–100). Calculated from cgroup counters. |
memoryUsage | number | Current memory usage in bytes |
memoryLimit | number | Memory limit in bytes (configured via container create or host limit) |
memoryPercent | number | Memory usage as a percentage of the limit (0–100) |
networkIn | number | Total bytes received over all network interfaces since container start |
networkOut | number | Total bytes transmitted over all network interfaces since container start |
blockRead | number | Total bytes read from block devices since container start |
blockWrite | number | Total bytes written to block devices since container start |
pids | number | Number of processes currently running inside the container |
status | string | success |
resource | string | container |
operation | string | stats |
Error Port
On failure, the error port receives errorCode, message, resource, and operation. In monitoring workflows, a stats retrieval failure should trigger an alert — if stats cannot be read, the container's health is unknown.
Sample Output
{
"cpuPercent": 12.4,
"memoryUsage": 157286400,
"memoryLimit": 536870912,
"memoryPercent": 29.3,
"networkIn": 10485760,
"networkOut": 5242880,
"blockRead": 2097152,
"blockWrite": 8388608,
"pids": 4,
"status": "success",
"resource": "container",
"operation": "stats"
}
Expression Reference
| Expression | Returns |
|---|
{{ $output.cpuPercent }} | CPU usage percentage (e.g. 12.4) |
{{ $output.cpuPercent > 85 }} | Boolean — true if CPU is above 85% |
{{ $output.memoryPercent }} | Memory usage as percentage of limit |
{{ $output.memoryPercent > 80 }} | Boolean — true if memory is above 80% of limit |
{{ ($output.memoryUsage / 1048576).toFixed(1) }} | Memory usage in MB (human-readable) |
{{ ($output.memoryLimit / 1048576).toFixed(0) }} | Memory limit in MB |
{{ ($output.networkIn / 1048576).toFixed(2) }} | Network in, megabytes |
{{ $output.pids }} | Number of processes in the container |
Node Policies & GuardRails
| Policy | Detail |
|---|
| Stats only available for running containers | Always verify container state with container/inspect before calling stats in workflows where the container may not be running. |
| Use scheduled triggers for continuous monitoring | Build resource monitoring by coupling this node with a ScheduledTrigger. Do not attempt to loop inside a single workflow execution for streaming-style monitoring. |
| Memory limit interpretation | If memoryLimit equals a very large number (e.g. system RAM total), no container-level memory limit has been set. Alert thresholds based on memoryPercent may not be meaningful in this case. |
| No remote TCP without TLS | Use tcptls for remote Docker hosts. |
| Always wire the error port | In monitoring workflows, stats failure indicates an unknown health state — route the error port to an alert, not a silent skip. |
Examples
Example 1: Alert on high CPU usage
// Scheduled trigger: every 2 minutes
// Node 1: container/stats
{ "resource": "container", "operation": "stats", "ContainerId": "api-service" }
// Node 2: If Condition
// Left: {{ $output.cpuPercent }}
// Op: greater than
// Right: 85
// → true branch: Slack alert "api-service CPU at {{ $output.cpuPercent.toFixed(1) }}%"
// → false branch: no-op
Example 2: Memory threshold auto-restart
// Node 1: container/stats
{ "resource": "container", "operation": "stats", "ContainerId": "worker-service" }
// Node 2: If Condition — memoryPercent > 90
// → true: container/restart worker-service, then Slack: "worker-service restarted due to memory pressure"
// → false: log metrics and continue
Example 3: Multi-container resource report
// For each container in a known list, collect stats and build a report:
const stats = $input; // output from container/stats loop
return {
reportLine: `${$vars.containerName}: CPU=${stats.cpuPercent.toFixed(1)}% | ` +
`Mem=${(stats.memoryUsage/1048576).toFixed(0)}MB/${(stats.memoryLimit/1048576).toFixed(0)}MB ` +
`(${stats.memoryPercent.toFixed(1)}%) | PIDs=${stats.pids}`
};
// Aggregate lines and send as single Slack or email digest
