containerlab events (#2898)

This PR add a containerlab events command. 

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 Docker's
event feed 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.

---------

Co-authored-by: hellt <[email protected]>

Author: FloSch62

cmd/events.go

@@ -0,0 +1,75 @@
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+	clabevents "github.com/srl-labs/containerlab/core/events"
+	clabutils "github.com/srl-labs/containerlab/utils"
+)
+
+func eventsCmd(o *Options) (*cobra.Command, error) {
+	c := &cobra.Command{
+		Use:   "events",
+		Short: "stream lab lifecycle and interface events",
+		Long: "stream container runtime events and interface updates for all running labs using the selected runtime\n" +
+			"reference: https://containerlab.dev/cmd/events/",
+		Aliases: []string{"ev"},
+		PreRunE: func(*cobra.Command, []string) error {
+			return clabutils.CheckAndGetRootPrivs()
+		},
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return eventsFn(cmd, o)
+		},
+	}
+
+	c.Flags().StringVarP(
+		&o.Events.Format,
+		"format",
+		"f",
+		o.Events.Format,
+		"output format. One of [plain, json]",
+	)
+
+	c.Flags().BoolVarP(
+		&o.Events.IncludeInitialState,
+		"initial-state",
+		"i",
+		o.Events.IncludeInitialState,
+		"emit the current container and interface states before streaming new events",
+	)
+
+	c.Flags().BoolVar(
+		&o.Events.IncludeInterfaceStats,
+		"interface-stats",
+		o.Events.IncludeInterfaceStats,
+		"include interface statistics updates when streaming events",
+	)
+
+	c.Flags().DurationVar(
+		&o.Events.StatsInterval,
+		"interface-stats-interval",
+		o.Events.StatsInterval,
+		"interval between interface statistics samples (requires --interface-stats)",
+	)
+
+	c.Example = `# Stream container and interface events in plain text
+containerlab events
+
+# Stream events as JSON
+containerlab events --format json`
+
+	return c, nil
+}
+
+func eventsFn(cmd *cobra.Command, o *Options) error {
+	opts := clabevents.Options{
+		Format:                o.Events.Format,
+		Runtime:               o.Global.Runtime,
+		IncludeInitialState:   o.Events.IncludeInitialState,
+		IncludeInterfaceStats: o.Events.IncludeInterfaceStats,
+		StatsInterval:         o.Events.StatsInterval,
+		ClabOptions:           o.ToClabOptions(),
+		Writer:                cmd.OutOrStdout(),
+	}
+
+	return clabevents.Stream(cmd.Context(), opts)
+}

cmd/options.go

@@ -52,6 +52,11 @@ func GetOptions() *Options {
 				MermaidDirection: "TD",
 				DrawIOVersion:    "latest",
 			},
+			Events: &EventsOptions{
+				Format:                "plain",
+				IncludeInterfaceStats: false,
+				StatsInterval:         time.Second,
+			},
 			ToolsAPI: &ToolsApiOptions{
 				Image:          "ghcr.io/srl-labs/clab-api-server/clab-api-server:latest",
 				Name:           "clab-api-server",
@@ -121,6 +126,7 @@ type Options struct {
 	Exec           *ExecOptions
 	Inspect        *InspectOptions
 	Graph          *GraphOptions
+	Events         *EventsOptions
 	ToolsAPI       *ToolsApiOptions
 	ToolsCert      *ToolsCertOptions
 	ToolsTxOffload *ToolsDisableTxOffloadOptions
@@ -353,6 +359,13 @@ type GraphOptions struct {
 	StaticDirectory  string
 }
 
+type EventsOptions struct {
+	Format                string
+	IncludeInitialState   bool
+	IncludeInterfaceStats bool
+	StatsInterval         time.Duration
+}
+
 type ToolsApiOptions struct {
 	Image          string
 	Name           string

cmd/root.go

@@ -29,6 +29,7 @@ func subcommandRegisterFuncs() []func(*Options) (*cobra.Command, error) {
 		execCmd,
 		generateCmd,
 		graphCmd,
+		eventsCmd,
 		inspectCmd,
 		redeployCmd,
 		saveCmd,

core/events/formatter.go

@@ -0,0 +1,116 @@
+package events
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+	"time"
+)
+
+type formatter func(aggregatedEvent) error
+
+func newFormatter(format string, w io.Writer) (formatter, error) {
+	normalized := strings.TrimSpace(strings.ToLower(format))
+	if normalized == "" {
+		normalized = "plain"
+	}
+
+	switch normalized {
+	case "plain":
+		return plainFormatter(w), nil
+	case "json":
+		return jsonFormatter(w), nil
+	default:
+		return nil, fmt.Errorf("output format %q is not supported, use 'plain' or 'json'", format)
+	}
+}
+
+func plainFormatter(w io.Writer) formatter {
+	return func(ev aggregatedEvent) error {
+		ts := ev.Timestamp
+		if ts.IsZero() {
+			ts = time.Now()
+		}
+		ts = ts.UTC()
+
+		actor := ev.ActorID
+		if actor == "" {
+			actor = ev.ActorName
+		}
+		if actor == "" {
+			actor = "-"
+		}
+
+		attrs := mergedEventAttributes(ev)
+		keys := make([]string, 0, len(attrs))
+		for k := range attrs {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+
+		parts := make([]string, 0, len(keys))
+		for _, k := range keys {
+			parts = append(parts, fmt.Sprintf("%s=%s", k, attrs[k]))
+		}
+
+		suffix := ""
+		if len(parts) > 0 {
+			suffix = " (" + strings.Join(parts, ", ") + ")"
+		}
+
+		_, err := fmt.Fprintf(
+			w,
+			"%s %s %s %s%s\n",
+			ts.Format(time.RFC3339Nano),
+			ev.Type,
+			ev.Action,
+			actor,
+			suffix,
+		)
+
+		return err
+	}
+}
+
+func jsonFormatter(w io.Writer) formatter {
+	encoder := json.NewEncoder(w)
+	encoder.SetEscapeHTML(false)
+
+	return func(ev aggregatedEvent) error {
+		copy := ev
+		copy.Attributes = mergedEventAttributes(ev)
+
+		return encoder.Encode(copy)
+	}
+}
+
+func mergedEventAttributes(ev aggregatedEvent) map[string]string {
+	if len(ev.Attributes) == 0 && ev.ActorName == "" && ev.ActorFullID == "" {
+		return nil
+	}
+
+	attrs := make(map[string]string, len(ev.Attributes)+2)
+	for k, v := range ev.Attributes {
+		if v == "" {
+			continue
+		}
+
+		attrs[k] = v
+	}
+
+	if ev.ActorName != "" {
+		attrs["name"] = ev.ActorName
+	}
+
+	if ev.ActorFullID != "" {
+		attrs["id"] = ev.ActorFullID
+	}
+
+	if len(attrs) == 0 {
+		return nil
+	}
+
+	return attrs
+}