# Docker Logs — Agent Usage Guide

> You are an AI agent. Use docker-logs tools to fetch complete raw logs from Docker containers.
> For label-filtered structured logs, use loki-gate tools.

## Quickstart

```bash
docker_container_list()                                           # See running containers
docker_worker_logs(worker="1")                                    # Tail worker 1 logs
docker_container_logs(container="ai-factory-orchestrator")        # Tail any container
```

## Tools

### docker_container_list

List running factory containers with type indicators.

```bash
docker_container_list()
```

### docker_worker_logs

Fetch complete logs from a worker container. Resolves worker numbers (1-4, "worker-2") to container names automatically. Captures **all** output including `console.log` and structured JSON.

```bash
docker_worker_logs(worker="1")
docker_worker_logs(worker="2", tail=500, search="error")
docker_worker_logs(worker="3", since="30m")
docker_worker_logs(worker="4", search="complete")
```

### docker_container_logs

Fetch complete logs from any Docker container by name. Use for orchestrator, Gitea, Postgres, or any container.

```bash
docker_container_logs(container="ai-factory-orchestrator")
docker_container_logs(container="ai-factory-gitea", tail=100)
docker_container_logs(container="ai-factory-worker-1", search="exit=")
docker_container_logs(container="ai-factory-postgres", since="1h")
```

## Docker vs Loki

| | Docker (`docker_*`) | Loki (`loki_*`) |
|---|---|---|
| **Captures** | All stdout/stderr (console.log + JSON) | Structured JSON logs only |
| **Per-container** | ✅ Exact container targeting | ❌ No container_name label |
| **Label filtering** | ❌ Text search only (`search` param) | ✅ Filter by agent, service |
| **Best for** | Complete job/worker output, console messages | Exploring by service/agent, error aggregation |
| **Requires** | Docker CLI + socket access | Loki running (port 3100) |

## Configuration

`.dockerlogs.yml`:

| Key | Default | Description |
|-----|---------|-------------|
| `tail` | `200` | Default number of log lines to tail |

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `docker_container_list()` fails | Docker daemon may not be running. Run `docker ps` manually. |
| Container not found | Use `docker_container_list()` to see exact names. |
| Empty logs | Try increasing `tail` or using `since` to widen the window. |
| Permission denied | Ensure current user has Docker access (`docker ps` works). |
| Need label filtering | For agent/service filtering, use `loki_query` or `loki_worker_logs`. |