# 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 runtime:** `docker`  
> Runtimes that do not implement the `events` API (or are not yet supported by Containerlab) will exit with an explanatory error.

## See also

- [`inspect interfaces`](inspect/interfaces.md) – produces a point-in-time view of the same interface details that `events` reports continuously.
- `docker events` – the raw runtime feed that Containerlab builds upon.
