# Docker Log Debugger

> Find and debug errors using Docker Compose logs. Use proactively when tests fail or services misbehave. PRIMARY - docker compose logs --since 15m | grep -iE -B 10 -A 10 "error|fail|exception"

- Skill: `majiayu000/docker-log-debugger` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/docker-log-debugger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/docker-log-debugger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/docker-log-debugger

---


# Docker Log Debugger

Find and debug errors by examining Docker container logs.

## Primary Command (Use This First!)
```bash
docker compose logs --since 15m | grep -iE -B 10 -A 10 "error|fail|exception"
```

Shows all errors from last 15 minutes with 10 lines of context before/after each match.

## When to Use

Use proactively when:
- Tests fail
- API endpoints return errors
- Worker jobs don't process
- Database/Redis connection issues
- Any service misbehaves

## Project Services

1. **api** - FastAPI (webhooks, HTTP endpoints)
2. **worker** - RQ worker (async jobs, enrichment, interventions)
3. **datastore** - PostgreSQL with pgvector
4. **redis** - Job queue

## Common Commands

```bash
# View all services (last 5 min)
docker compose logs --since 5m

# View specific service
docker compose logs api --since 5m
docker compose logs worker --since 5m

# Follow logs in real-time
docker compose logs -f api worker

# View last N lines
docker compose logs --tail 100 worker

# Search for specific patterns
docker compose logs worker --since 5m | grep -i "KeyError"
docker compose logs api --since 5m | grep -i "connection"
docker compose logs worker --since 5m | grep -i "langfuse"

# Service health
docker compose ps
docker compose restart worker
```

## Time Filters

Use with `--since`: `5m`, `10m`, `1h`, `30s`, `2h30m`

## Quick Debugging

### Test Failed
```bash
docker compose logs --since 15m | grep -iE -B 10 -A 10 "error|fail|exception"
docker compose ps  # Check if services are running
```

### Worker Job Issues
```bash
docker compose logs worker --since 5m | grep -i "exception\|error"
docker compose logs worker --since 5m | grep -i "job\|enrich"
```

### API Errors
```bash
docker compose logs api --since 5m | grep -E "(400|401|404|500|503)"
docker compose logs api --since 5m | grep -A 10 "Traceback"
```

### Database/Redis Issues
```bash
docker compose logs datastore --since 5m
docker compose logs api worker --since 5m | grep -i "connection\|postgres\|redis"
```

### Langfuse Errors
```bash
docker compose logs worker --since 5m | grep -i "langfuse\|prompt.*not found"
```

## Common Error Patterns

| Error | Check |
|-------|-------|
| `KeyError: 'field'` | Fetch Langfuse prompt to see actual schema |
| `Connection refused` | `docker compose ps` - check service status |
| `ModuleNotFoundError` | May need `docker compose build api worker` |
| `Job not found` | Check Redis running, worker processing jobs |
| `OpenAI API error` | Verify OPENAI_API_KEY, check rate limits |
| `alembic` errors | Run migrations: `docker compose exec api alembic upgrade head` |

## Quick Reference

```bash
# 🔥 Find all errors with context
docker compose logs --since 15m | grep -iE -B 10 -A 10 "error|fail|exception"

# Service status
docker compose ps

# Restart services
docker compose restart

# Full reset
docker compose down && docker compose up -d

# Watch live
docker compose logs -f api worker

# Save for analysis
docker compose logs --since 15m > debug.log
```