system_events
Monitor Docker activity by streaming real-time events with filters, limits, and timeout bounds. Use it to react to container or service changes without polling snapshots.
Instructions
Stream real-time events from the Docker server, bounded by limit events or timeout_seconds.
Returns when limit events are collected or timeout_seconds elapses, whichever comes first
(limit caps memory; timeout_seconds caps how long the call blocks — without it a quiet daemon
would block indefinitely, since the stream only yields on an actual event).
Caveat for ssh:// daemons: docker-py can't cancel an SSH stream, so the timeout_seconds
watchdog can't interrupt a fully idle stream — bound with until/limit (or a non-SSH endpoint).
"Wait for the next matching event" idiom: pass limit=1 with filters narrowed to what you
care about (e.g. {"type": "container", "event": "health_status"}) and a generous
timeout_seconds. This blocks until that one event arrives (or the timeout elapses, returning an
empty list) instead of re-polling a snapshot on a timer — there's no separate wait tool for this
since the filtering this call already does covers it.
args: since - Show events created since this timestamp until - Show events created until this timestamp filters - Filters to apply to the event stream limit - Max events to return (default 100) timeout_seconds - Max wall-clock seconds before returning what was collected (default 30) returns: list - A list of decoded event dicts (length <= limit)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No | ||
| until | No | ||
| filters | No | ||
| timeout_seconds | No |