feat: label-based filtering added to `nerdctl events` by Mujib-Ahasan · Pull Request #4999 · containerd/nerdctl

Mujib-Ahasan · 2026-06-23T19:27:11Z

Description

This PR adds support for label-based filtering in nerdctl events. Users can now filter the event stream using container labels, for example:

nerdctl events --filter label=com.example.app=myapp

Fixes: #4690

The implementation resolves container metadata from incoming events and matches the configured label filter before displaying the event. This helps users focus on events related to a specific workload in environments with so many running containers.

I have tested this out in my local machine before pushing it.

sathiraumesh · 2026-06-24T07:26:14Z

-
-			eOut := EventOut{e.Timestamp, id, e.Namespace, e.Topic, TopicToStatus(e.Topic), string(out)}
+			if id != "" {
+				container, err := client.ContainerService().Get(ctx, id)


probably can improve like

if container, err := client.ConatinerService.Get(ctx, id); err == nil { labels = container.Labels }

AkihiroSuda · 2026-06-24T17:58:09Z

Needs tests
https://github.com/containerd/nerdctl/blob/main/cmd/nerdctl/system/system_events_linux_test.go

Mujib-Ahasan · 2026-06-25T18:49:07Z

@AkihiroSuda there are so many failed checks and after surfacing little bit I strongly feels they are flaky and not related to the changes in this PR.

sathiraumesh · 2026-06-26T08:34:20Z

-
-			eOut := EventOut{e.Timestamp, id, e.Namespace, e.Topic, TopicToStatus(e.Topic), string(out)}
+			if id != "" {
+				if container, err := client.ContainerService().Get(ctx, id); err == nil {


the err is ignored here may be good idea to add a log

AkihiroSuda · 2026-06-29T06:50:10Z

Please squash the commits and rebase with the current main branch

Mujib-Ahasan · 2026-06-29T09:11:36Z

I squashed commits and rebased on main then force pushed.
Cc @AkihiroSuda

AkihiroSuda · 2026-06-30T10:23:57Z

2026-06-29T19:48:08.7201314Z === Failing tests ===
2026-06-29T19:48:08.7201753Z TestEventFilters
2026-06-29T19:48:08.7202138Z TestEventFilters/LabelFilter
2026-06-29T19:48:08.7202617Z TestEventFilters/LabelKeyOnlyFilter

https://github.com/containerd/nerdctl/actions/runs/28356414001/job/84140963740?pr=4999

The tests are failing with Docker v28.

Please try rebasing after we merge:

CI: update Docker (29.6.1) #5021 (still draft, will try to complete by tomorrow)

Mujib-Ahasan · 2026-07-01T10:24:48Z

Copilot telling the reason is this:

The failing event tests are a race: your test starts events in the background then runs a short-lived container (no -d / no long-lived command). the container often starts and exits so quickly that the events subscriber misses the "start" event (only sees "die"/"destroy"), causing the expectation "Status":"start" to fail. Fix the tests so the container stays running (or wait for events subscription readiness) and the test will reliably observe the "start" event.

so what I did: $ git diff

-       helpers.Ensure("run", "--rm", "--label", data.Labels().Get("containerLabel"), testutil.CommonImage)
+       helpers.Ensure(
+               "run",
+               "-d",
+               "--name", data.Identifier(),
+               "--label", data.Labels().Get("containerLabel"),
+               testutil.CommonImage,
+               "tail", "-f", "/dev/null",
+       )
+       helpers.Ensure("rm", "-f", data.Identifier())

this gives container enough time to live. Run test, then cleanup.

@AkihiroSuda is this a right direction I am following?

AkihiroSuda · 2026-07-02T17:01:44Z

this gives container enough time to live. Run test, then cleanup.

Don't you need some time.Sleep between run and rm?

Mujib-Ahasan · 2026-07-02T19:33:14Z

I think the test is failing because it iss running against Docker host rather than nerdctl. Would it make sense to add Require: require.Not(nerdtest.Docker) so this test only runs for nerdctl?

AkihiroSuda · 2026-07-03T01:19:13Z

I think the test is failing because it iss running against Docker host rather than nerdctl. Would it make sense to add Require: require.Not(nerdtest.Docker) so this test only runs for nerdctl?

Any reason not to make it Docker-compatible?

Mujib-Ahasan · 2026-07-03T18:22:03Z

Any reason not to make it Docker-compatible?

I apologize!😅

I think I managed to solve that particular test!

Copilot

Pull request overview

Adds label-based filtering support to nerdctl events by enriching incoming events with container labels and extending the filter engine to match label= filters, along with integration coverage for the new behavior.

Changes:

Extend event filtering to support --filter label=key[=value].
Resolve container labels for events (via container metadata lookup) and attach them to the internal event model used for filtering/formatting.
Add Linux integration tests validating label filtering (key/value and key-only).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
pkg/cmd/system/events.go	Adds `Labels` to event output model, implements `LABEL` filter logic, and retrieves container labels during event processing.
cmd/nerdctl/system/system_events_linux_test.go	Adds integration tests covering label-based event filtering.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+	case "LABEL":
+		return func(e *EventOut) bool {
+			if len(e.Labels) == 0 {
+				return false
+			}
+
+			parts := strings.SplitN(filterValue, "=", 2)
+			if len(parts) == 1 {
+				_, ok := e.Labels[parts[0]]
+				return ok
+			}
+
+			return e.Labels[parts[0]] == parts[1]
+		}, nil


@@ -197,8 +213,14 @@
 					id = data["container_id"].(string)
 				}
 			}
-
-			eOut := EventOut{e.Timestamp, id, e.Namespace, e.Topic, TopicToStatus(e.Topic), string(out)}
+			if id != "" {


+			if id != "" {
+				if container, err := client.ContainerService().Get(ctx, id); err != nil {
+					log.G(ctx).WithError(err).WithField("containerID", id).Debug("failed to retrieve container labels")
+				} else {
+					labels = container.Labels
+				}
+			}


Signed-off-by: Mujib Ahasan <ahasanmujib8@gmail.com> test case added Signed-off-by: Mujib Ahasan <ahasanmujib8@gmail.com> events: log errors when retrieving container labels Signed-off-by: Mujib Ahasan <ahasanmujib8@gmail.com>

sathiraumesh reviewed Jun 24, 2026

View reviewed changes

AkihiroSuda reviewed Jun 24, 2026

View reviewed changes

Mujib-Ahasan requested a review from AkihiroSuda June 25, 2026 11:01

sathiraumesh suggested changes Jun 26, 2026

View reviewed changes

Mujib-Ahasan requested a review from sathiraumesh June 26, 2026 20:24

Mujib-Ahasan force-pushed the label-based-filtering branch from beb85a4 to e362fdd Compare June 29, 2026 07:41

AkihiroSuda added this to the v2.4.0 milestone Jun 30, 2026

Mujib-Ahasan force-pushed the label-based-filtering branch from e362fdd to 9992dfa Compare July 1, 2026 08:24

Mujib-Ahasan force-pushed the label-based-filtering branch from 9992dfa to 2620492 Compare July 2, 2026 16:04

Mujib-Ahasan force-pushed the label-based-filtering branch from 2620492 to b35453e Compare July 2, 2026 19:08

Mujib-Ahasan force-pushed the label-based-filtering branch from b35453e to bb6a8c1 Compare July 3, 2026 16:33

AkihiroSuda requested review from Copilot and removed request for sathiraumesh July 5, 2026 19:09

Copilot started reviewing on behalf of AkihiroSuda July 5, 2026 19:09 View session

Copilot AI reviewed Jul 5, 2026

View reviewed changes

feature: label-based filtering added

c76a63b

Signed-off-by: Mujib Ahasan <ahasanmujib8@gmail.com> test case added Signed-off-by: Mujib Ahasan <ahasanmujib8@gmail.com> events: log errors when retrieving container labels Signed-off-by: Mujib Ahasan <ahasanmujib8@gmail.com>

Mujib-Ahasan force-pushed the label-based-filtering branch from bb6a8c1 to c76a63b Compare July 7, 2026 08:20

Uh oh!

Conversation

Mujib-Ahasan commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

sathiraumesh Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Mujib-Ahasan commented Jun 25, 2026

Uh oh!

sathiraumesh Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda commented Jun 29, 2026

Uh oh!

Mujib-Ahasan commented Jun 29, 2026

Uh oh!

AkihiroSuda commented Jun 30, 2026

Uh oh!

Mujib-Ahasan commented Jul 1, 2026

Uh oh!

AkihiroSuda commented Jul 2, 2026

Uh oh!

Mujib-Ahasan commented Jul 2, 2026

Uh oh!

AkihiroSuda commented Jul 3, 2026

Uh oh!

Mujib-Ahasan commented Jul 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Mujib-Ahasan commented Jun 23, 2026 •

edited

Loading