Skip to main content
Yes, docker-agent-tail needs Docker daemon to be running and accessible. It connects to the Docker socket to list and stream container logs.
Add your user to the docker group:
sudo usermod -aG docker $USER
Then log out and back in for the change to take effect.
Yes! Use the --compose flag to automatically discover and tail all services in a docker-compose.yml file.
docker-agent-tail works with json-file and journald log drivers. Other drivers won’t support real-time streaming.
Yes, use --exclude to skip lines matching a regex pattern. Use --mute to hide matching containers from terminal output while still writing them to log files.
Logs are saved automatically to the ./logs directory (configurable with --output). Each session creates a timestamped directory with combined.jsonl and per-container .jsonl files. A latest symlink always points to the most recent session.
--exclude completely skips log lines matching the regex — they are not shown in the terminal and not written to files. --mute hides matching containers from terminal output but still writes their logs to files for later analysis.
Log files use JSON Lines (.jsonl) format. Each line is a valid JSON object with fields like ts, container, stream, and either message (plain text) or the original structured fields (JSON container output). Structured JSON from containers is automatically merged with metadata and levels are normalized. No special flag is needed — JSONL is the default file format.
Use lnav, a terminal-based log viewer. Install the format definition once with docker-agent-tail lnav-install, then view logs with:
lnav logs/latest/combined.jsonl
lnav supports SQL queries, regex filtering, and color-coded log levels. See the lnav integration guide for details.
Use the clean command to remove old sessions:
# Keep the 5 most recent sessions (default)
docker-agent-tail clean

# Keep only the 3 most recent
docker-agent-tail clean --retain 3
Use --since with a Go duration (e.g., 5m, 1h, 30s) to only show logs from that duration ago:
docker-agent-tail --all --since 5m
Containers with TTY attached may output raw streams. docker-agent-tail detects this and handles it appropriately.
Yes, pass a glob pattern as an argument to match container names. For example: web-* matches all containers starting with “web-”.
Docker doesn’t allow duplicate container names, so this shouldn’t happen. Each container must have a unique name.
Yes! Set the DOCKER_HOST environment variable to connect to a remote Docker daemon.
That depends on your containers’ verbosity and how long you run docker-agent-tail. Use --exclude to reduce file size, and docker-agent-tail clean to remove old sessions.
No. docker-agent-tail reads from Docker’s log buffers and doesn’t interfere with container execution.
Press Ctrl+C in the terminal. This cleanly closes all log streams and exits gracefully.
Yes! Use --output to save logs as artifacts. Use --no-color or --json for cleaner log files when piping to other tools.
Check the container’s log driver: docker inspect --format='{{.HostConfig.LogConfig.Type}}' <container>. docker-agent-tail only works with json-file and journald drivers. Other drivers (e.g., syslog, awslogs, fluentd) don’t support Docker’s ContainerLogs API.
CodeMeaning
0Success
1General error
2No containers found matching criteria
3Docker daemon error (connection failed, timeout)
64Usage error (invalid flags or arguments)
Yes! Use the --json flag to output structured JSON Lines to stdout instead of human-readable format. This is useful for piping to jq or other tools.
Use --dry-run to list sessions that would be deleted without actually removing them:
docker-agent-tail clean --dry-run
docker-agent-tail clean --retain 2 --dry-run

​
Still Have Questions?

Check out the CLI reference for complete documentation, or visit the GitHub repository to file an issue.