events command#

Description#

The events command streams lifecycle updates for every Containerlab resource and augments them with interface change notifications collected from the container network namespaces. The output combines the selected runtime's event feed (for example Docker) with the netlink information that powers containerlab inspect interfaces, so you can observe container activity and interface state changes in real time without selecting a specific lab.

Usage#

containerlab [global-flags] events [local-flags]

aliases: ev

The command respects the global flags such as --runtime, --debug, or --log-level. It adds local options:

--format controls the output representation (plain, json).
--initial-state emits a snapshot of currently running containers and their interface states before following live updates.
--interface-stats enables periodic interface counter sampling; leave unset to report only lifecycle and state changes.
--interface-stats-interval customizes how frequently statistics are collected (for example 500ms, 2s, 1m).

When invoked with no arguments it discovers all running labs and immediately begins streaming events; new labs that start after the command begins are picked up automatically.

Event format#

In the default plain format every line mirrors the docker events format:

<timestamp> <type> <action> <actor> (<key>=<value>, ...)

Runtime events show the short container ID as the actor and include the original attributes supplied by the container runtime (for example image, name, containerlab, scope, …). Container events are also enriched with mgmt_ipv4, mgmt_ipv6, and ports (published/exposed ports) when those values are available. When --initial-state is enabled the stream starts with container <state> snapshots (for example container running) that carry an origin=snapshot attribute.
Interface events use type interface and origin=netlink in the attribute list. They also report interface-specific data such as ifname, state, mtu, mac, type, alias, and the lab label. The actor is still the container short ID, and the container name is supplied in the attributes (name=...).
Interface notifications are emitted when a link appears, disappears, or when its relevant properties (operational state, MTU, alias, MAC address, type) change. Initial snapshots use the snapshot action when --initial-state is requested. When interface statistics are enabled the stream also includes interface stats updates with byte/packet counters and rate estimates.

When --format json is used, each event becomes a single JSON object on its own line. The fields match the plain output (timestamp, type, action, actor_id, actor_name, actor_full_id) and include an attributes map with the same key/value pairs that the plain formatter prints.

Examples#

Watch an existing lab and new deployments#

$ containerlab events
2024-07-01T11:02:56.123456000Z container start 5d0b5a9ad3f1 (containerlab=frr-lab, image=ghcr.io/srl-labs/frr, name=clab-frr-lab-frr01, ports=0.0.0.0:2222/tcp->22;0.0.0.0:830/tcp->830)
2024-07-01T11:02:57.004321000Z interface create 5d0b5a9ad3f1 (ifname=eth0, index=22, lab=frr-lab, mac=02:42:ac:14:00:02, mtu=1500, name=clab-frr-lab-frr01, origin=netlink, state=up, type=veth)
2024-07-01T11:02:57.104512000Z interface update 5d0b5a9ad3f1 (ifname=eth0, index=22, lab=frr-lab, mac=02:42:ac:14:00:02, mtu=9000, name=clab-frr-lab-frr01, origin=netlink, state=up, type=veth)
2024-07-01T11:05:12.918273000Z container die 5d0b5a9ad3f1 (containerlab=frr-lab, exitCode=0, image=ghcr.io/srl-labs/frr, name=clab-frr-lab-frr01)
2024-07-01T11:05:13.018456000Z interface delete 5d0b5a9ad3f1 (ifname=eth0, index=22, lab=frr-lab, name=clab-frr-lab-frr01, origin=netlink, state=up, type=veth)

The stream contains all currently running labs and stays active to capture subsequent deployments, restarts, or interface adjustments.

Include existing resources in the stream#

$ containerlab events --initial-state
2024-07-01T11:02:55.912345000Z container running 5d0b5a9ad3f1 (containerlab=frr-lab, image=ghcr.io/srl-labs/frr, name=clab-frr-lab-frr01, origin=snapshot, ports=0.0.0.0:2222/tcp->22;0.0.0.0:830/tcp->830, state=running)
2024-07-01T11:02:55.912678000Z interface snapshot 5d0b5a9ad3f1 (ifname=eth0, index=22, lab=frr-lab, mac=02:42:ac:14:00:02, mtu=1500, name=clab-frr-lab-frr01, origin=netlink, state=up, type=veth)
…

This mode begins with a point-in-time view of every running container and interface before switching to live updates.

Include interface statistics#

containerlab events --interface-stats

Statistics are disabled by default. Enabling them augments the feed with periodic counter samples in addition to lifecycle and state changes. Use --interface-stats-interval to balance fidelity with overhead: values between 1s and 5s work well for most labs, while larger deployments may prefer longer intervals (for example 10s) to avoid excessive sampling load.

Use with alternative runtimes#

Containerlab streams events from the runtime selected via the global --runtime flag.

Currently supported runtimes:

docker
c9s

With --runtime c9s, events are backed by kubernetes watches for Clabernetes Topology and Node resources and labeled Pods. They use the actions and attributes of the Docker runtime: a node is a container (create, start, kill, stop, die, destroy, health_status: …) described by the same labels, and the interface events (snapshot, create, update, delete, stats) report the node's lab link interfaces, eth0 and lo under the names a Docker container of the node has. Interface state and statistics are sampled inside the device containers, not through local host netlink. The stream covers every namespace by default; --namespace (or CLAB_KUBE_NAMESPACE) limits it to one namespace, and -t/--name to one lab. With Docker and Podman the lab selection is ignored and every lab is streamed. The c9s runtime manual lists the attributes and the few Docker attributes c9s has no equivalent for.

Runtimes that do not implement the events API, or are not yet supported by Containerlab, will exit with an explanatory error.