Platform monitoring

Citadel reports CPU, memory, network, and Docker storage filesystem usage for Local, regular Agent, and Platform Edge Agent connections.

Open the Platform's Stats tab for host history, or a container's Stats tab for an individual workload. If the header reports interrupted live updates, displayed information may be outdated; follow connection troubleshooting.

Choose a time rangeCopy Anchor Link

The shared History dropdown keeps all charts on the same timeline. 1 hour is selected initially. Quick ranges include 15 minutes, 6 hours, 24 hours, 48 hours, 7 days, Today, and Yesterday.

Chart times use your browser's timezone. Relative ranges and Today follow incoming live samples; Yesterday stays fixed. Historical summaries use the last sample in the selected range. Charts use straight segments and leave gaps where readings are missing. The Y axis shows percentages or byte units. Metrics are retained for seven days; a new or disconnected resource may have less history.

History and live charts use averages: 10-second buckets up to one hour, 30-second buckets up to six hours, one-minute buckets up to one day, five-minute buckets up to three days, and 15-minute buckets for longer ranges. These averages can smooth brief spikes; narrow the range for finer detail.

Statistics API endpoints accept minutes=15|60|360|1440|10080, or inclusive Unix second bounds from and to. Omitting to uses the current time. Existing hours=24|48|72 requests remain supported, and omitting all range parameters keeps the API's 24-hour default. Do not combine range formats.

Current usage values remain instantaneous. Live observations accumulate into averages without discarding samples when a Stats tab stays open. Saved history takes precedence in overlapping buckets; the bucket already in progress when the tab opens stays at its saved average until history is reloaded. Subsequent buckets update live.

Container network and disk I/OCopy Anchor Link

The container Network Usage chart has two views: Accumulated shows received and sent bytes recorded during the selected period; Throughput shows receive and send rates in bytes per second. The two header totals always cover the selected period, including when viewing throughput.

Disk I/O offers the same views for block-device reads and writes. Both charts default to Accumulated. Each chart's view selection is saved separately in your browser's localStorage and shared across container and Platform statistics. This measures device I/O reported by Docker, rather than disk space used. Cached file reads may not generate device reads, and network filesystems may not appear in these counters.

Rates divide recorded bytes by measured elapsed time in each chart bucket, so long and short intervals receive the correct weight. The first sample establishes a baseline, so at least two observations are needed. Counter resets are handled per container or Swarm Task. Missing readings and an unobserved reset can leave some traffic unrecorded.

Hosts that do not report block I/O show an unavailable message. Older statistics remain unavailable for Disk I/O; new samples appear after Core and connected Agents have been updated. Individual containers, Deployments and Swarm Tasks and Services share these charts.

Diagnose a missed container readingCopy Anchor Link

A Container statistics sample failed warning identifies docker_container_id, error_kind, retryable, and the Docker error. Local Core sampling includes the Platform ID in its log span; Agent sampling reports the details in that Agent's logs. Successful container readings continue, and sampling tries again on the next cycle.

A container that stops or disappears between discovery and sampling is logged as Container statistics sample skipped at debug level. To include these lifecycle races and cycle counts, use RUST_LOG=info,citadel_docker=debug,citadel_server::workers::platforms=debug and restart the process whose logs you are inspecting. Repeated timeout or daemon errors require investigating the Docker daemon and the identified container; a missed reading alone does not mean its workload failed.

History across deploymentsCopy Anchor Link

Deployment statistics follow the Deployment ID across container replacements. Stack charts group history by Compose service within the Stack, and Swarm service history survives task replacement and scaling. Replacements in the same known replica slot share a time bucket; separate replicas contribute to the service total. Unknown replica identities stay separate.

Workload samples are retained for seven days independently of current container inventory. History remains readable during a replacement when no container is present. A newly created workload starts its own history even if it reuses a name. Individual container charts still describe only that container instance. Missing observations remain gaps.

Compose replica continuity uses the replica number reported by Docker. Samples without that identity keep their original instance identity. Live Stack totals wait for readings from every running replica in the time bucket; partial live readings do not replace a complete saved total.

Investigate resource pressureCopy Anchor Link

1. Open the affected Platform and check that it is connected and receiving current readings. An old chart cannot confirm recovery.
2. Use Stats to see whether the increase is sustained and when it started. Compare that time with recent deployments, builds, and other operations.
3. For CPU or memory pressure, inspect the busy containers' Stats and logs. For disk pressure, check the filesystem described below before removing data.
4. After addressing the cause, confirm fresh readings and application health, then review the alert's resolution state.

Assign notification channels to the built-in capacity rules under Configuration → Alert Rules to receive future alerts. Custom thresholds and required-match counts require Advanced Alerting.

Container memoryCopy Anchor Link

The Containers table's Memory column and memory alerts use Docker's working set, followed by the memory limit. Container, Stack, Deployment and Swarm Service memory charts offer two views. Working set is the default; the same browser remembers your choice across these pages.

• Breakdown stacks Non-cache memory, Active file cache, and Inactive file cache. Non-cache memory includes anonymous allocations, shared memory and kernel charges; it is not process RSS or heap size.
• Working set shows one series matching Docker's calculation. Changing the chart view does not change alert thresholds or table values.

Working set = raw container memory − inactive file cache
Non-cache memory = working set − active file cache
Total charged = non-cache memory + active file cache + inactive file cache

Active file cache can remain after a deployment or script finishes. It is potentially reclaimable filesystem memory, not necessarily an application leak. The breakdown tooltip also shows working set and total charged memory.

The working set follows Docker's memory calculation: total_inactive_file on cgroup v1 and inactive_file on cgroup v2. The active cache measurement uses the corresponding total_active_file or active_file counter. Shared memory and tmpfs are not subtracted as filesystem cache. Missing or inconsistent counters do not produce a fabricated breakdown. Windows containers can report a working set without a Linux cache breakdown.

Earlier samples keep their working-set and inactive-cache readings. They have no active-cache measurement, so Breakdown leaves gaps and offers Working set to view them. Buckets or service totals with incomplete breakdown coverage also remain unavailable. No historical data is rewritten.

The containers table keeps working set / memory limit as its Memory value. Hover, focus, or click the value to open a breakdown card showing memory excluding file cache, active file cache, and inactive file cache. Click pins the card; Escape dismisses it. Missing breakdown readings appear as unavailable, including stack summaries when a member lacks the required reading. Expanded stack children use a subtle background tint and indentation to distinguish them from other rows.

Disk UsageCopy Anchor Link

Disk Usage is the capacity of the host filesystem containing Docker's configured data root. It is not the sum of image, container, volume, and build cache sizes, and it does not represent reclaimable Docker space.

Citadel shows current used and total capacity in the Platform summary and historical percentage usage in the Platform Stats tab. Missing readings appear as unavailable rather than zero.

Citadel includes these system rules:

When both thresholds match, the Critical rule takes precedence. Configure channels on both rules if you need notifications at both severities; cooldown does not send periodic reminders for an open incident.

Inspect unused images and volumes before deleting anything. Other files on the same filesystem can also consume space, so Docker cleanup may not remove the cause. Confirm that a volume's data is no longer needed before deleting it.

If disk usage is unavailable, verify the host mount below and the Agent version. A missing reading does not mean the filesystem is empty or that a disk alert has recovered.

Backup SummaryCopy Anchor Link

The platform summary counts backup policies attached to that platform through a Docker volume, bind mount, stack, deployment, or managed Swarm Service. Citadel control-plane backups are instance-wide, so they are shown on the main Backups page and are not included in a platform's total. See Backups for details.

Container MountCopy Anchor Link

Linux Core and Platform Agent containers need this bind mount:

/:/host:ro

The mount lets Citadel read filesystem capacity for Docker's configured data root, including a custom data root on another mounted filesystem. It is read-only, but it exposes host paths to the trusted Citadel process. Citadel does not browse or transfer host files through this feature.

Removing the mount disables only disk metrics. CPU, memory, network, and Docker operations continue. Include the mount when configuring Core and Platform Agent containers. Build-pool-only Edge Agents do not need it.

Custom packaging can change the in-container mount location with:

CITADEL_HOST_ROOT=/host

The environment value and actual bind target must match.

For ZFS, Citadel reports the mounted dataset or filesystem containing Docker's data root, not whole-pool allocation.