system_events
Stream real-time Docker events with filters, returning when a limit or timeout is reached. Wait for a specific event instead of polling.
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 timeout_seconds: Max wall-clock seconds before returning what was collected
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 |