Feature Request: Support --since, --until, and label filtering in `nerdctl events`

[tinovyatkin]

Summary

The nerdctl events command has limited support for event filtering compared to Docker CLI. Specifically, the --since, --until, and label-based filtering options either don't work as expected or are not implemented.

Docker Documentation

From Docker events reference:

--since and --until

Filter events by time. Supports Unix timestamps, date formatted timestamps, or Go duration strings.

Supported formats:

• Unix timestamps: 1483283804 or 1483283804.123456789
• RFC3339: 2006-01-02T15:04:05
• Go duration strings: 10m, 1h30m

# Events from the last 10 minutes
docker events --since '10m'

# Events in a time range
docker events --since '2024-01-05T00:35:30' --until '2024-01-05T00:36:05'

Label filtering

# Filter events by container label
docker events --filter 'label=com.example.app=myapp'

Podman Compatibility

Podman fully supports these filters:

• --since: All events created since the given timestamp
• --until: All events created until the given timestamp
• Accepts both RFC3339Nano timestamps and Go duration strings (e.g., 10m, 5h)

Reference: Podman events documentation

Use Cases

1. IDE/Editor Extensions: VS Code Docker extension uses --since to fetch only recent events when reconnecting to the event stream, avoiding the overhead of processing historical events.

2. CI/CD Pipelines: Build systems often need to monitor events within specific time windows for deployment verification.

3. Monitoring Tools: Dashboard and alerting tools filter events by time range and labels for targeted monitoring.

4. Development Debugging: Developers frequently need to see events from a specific time period when troubleshooting issues.

Current Workaround

For VS Code Docker extension users, a workaround has been implemented in PR #327 that:

• Parses relative time strings (e.g., 1m, 30s) and applies client-side filtering
• Throws a clear error when label filtering is requested

Current Behavior

# These options may be silently ignored or produce unexpected results
nerdctl events --since '10m'
nerdctl events --filter 'label=key=value'

Expected Behavior

# Show events from the last 10 minutes
nerdctl events --since '10m'

# Show events in a time window
nerdctl events --since '2024-01-10T10:00:00' --until '2024-01-10T11:00:00'

# Filter by label
nerdctl events --filter 'label=com.docker.compose.project=myproject'

Additional Context

This feature gap was identified while implementing Finch support for the VS Code Docker extension. The containerd event API provides timestamps, so implementing these filters should be feasible. Full Docker CLI compatibility for event filtering would improve tooling integration for users choosing Finch/nerdctl as their container runtime.

[mojozizo]

@tinovyatkin I'd be happy to work on this issue