log-search

# log-search skill

Use this skill when the user wants to:
- Search log history for an error message or keyword
- Find which containers logged a specific string
- Filter search results by level or container
- Query the search API programmatically

## CLI search

```
clv search "<query>"
```

Searches all stored log lines using SQLite FTS5 full-text search.

Options:

```
--container <name>   Limit search to one container
--level <levels>     Filter by level: error,warn,info,debug
--limit <n>          Max results (default 50)
--format <text|json> Output format (default: text)
```

Examples:

```
# Find all "connection refused" occurrences
clv search "connection refused"

# Errors only in the worker container
clv search "timeout" --container worker --level error

# JSON output for scripting
clv search "ECONNREFUSED" --format json

# Raise the result cap
clv search "deprecated" --limit 200
```

## Output format

Text output columns: TIME, CONTAINER, LEVEL, MESSAGE

The query term is highlighted in the MESSAGE column (terminal: amber/bold; web UI: yellow background chip).

JSON output per result:

```json
{
  "id": 1794,
  "container_name": "worker",
  "ts": "2026-03-20T15:50:14.600Z",
  "level": "error",
  "stream": "stderr",
  "msg": "Job failed: SMTP connection refused",
  "raw": "{\"level\":\"error\",\"msg\":\"Job failed: SMTP connection refused\",...}"
}
```

## HTTP API

### Search endpoint

```
GET /api/logs/search?q=<query>[&container=<name>][&level=<levels>][&limit=<n>]
```

Response:

```json
{
  "query": "connection refused",
  "total": 8,
  "results": [
    {
      "id": 1201,
      "container_name": "worker",
      "ts": "2026-03-20T15:50:14.600Z",
      "level": "error",
      "stream": "stderr",
      "msg": "Job failed: SMTP connection refused",
      "raw": "..."
    }
  ]
}
```

### Other log endpoints

```
GET /api/logs?container=<name>[&level=<levels>][&since=<iso>][&limit=<n>]
```

Returns paginated log lines for a container. Use `since` with an ISO timestamp for pagination.

```
GET /api/logs/:id
```

Returns a single log line by ID with full raw field.

## CI / scripting example

Check for any ERROR logs in the last run before promoting:

```bash
ERRORS=$(clv search "ERROR" --container api --level error --format json | jq '.total')
if [ "$ERRORS" -gt 0 ]; then
  echo "Found $ERRORS errors in api container - aborting deploy"
  exit 1
fi
```

## Web UI search

Open http://127.0.0.1:3200, click "Search logs" in the sidebar.

- Type a query and press Enter or click Search
- Results show across all containers with highlighted match terms
- Use level chips to narrow results
- Click any result row to expand full JSON payload

## FTS notes

- Search is case-insensitive
- Phrase search: use quotes - "connection refused"
- Prefix search: append * - "connectio*"
- The FTS index covers the `msg` field only, not the raw JSON body
- Results are ordered by timestamp descending (most recent first)