> ## Documentation Index
> Fetch the complete documentation index at: https://proxy-hopper.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging

> Log levels, formats, and what each level tells you.

## Log levels

Log levels in increasing verbosity: `ERROR`, `WARNING`, `INFO` (default), `DEBUG`, `TRACE`.

| Level     | What you see                                                           |
| --------- | ---------------------------------------------------------------------- |
| `ERROR`   | Backend connection failures, unrecoverable errors                      |
| `WARNING` | IPs quarantined, connection errors, requests dropped                   |
| `INFO`    | Server start/stop, IP released from quarantine                         |
| `DEBUG`   | Request dispatch (method, URL, IP), retry decisions, pool seeding      |
| `TRACE`   | Every queue push/pop, every Redis command, every connection open/close |

```bash theme={}
proxy-hopper run --config config.yaml --log-level DEBUG
```

## Log formats

### Text (default)

Human-readable, suitable for local development:

```
2024-01-15 10:23:45 INFO  server started host=0.0.0.0 port=8080 backend=memory
2024-01-15 10:23:46 DEBUG dispatch method=GET url=https://api.example.com ip=10.0.0.1:3128 target=general
2024-01-15 10:23:46 WARNING quarantine ip=10.0.0.2:3128 target=general failures=5
```

### JSON

Structured output for log aggregators (Fluentd, Datadog, GCP Cloud Logging):

```bash theme={}
proxy-hopper run --config config.yaml --log-format json
```

```json theme={}
{"timestamp": "2024-01-15T10:23:45Z", "level": "INFO", "event": "server started", "host": "0.0.0.0", "port": 8080, "backend": "memory"}
{"timestamp": "2024-01-15T10:23:46Z", "level": "DEBUG", "event": "dispatch", "method": "GET", "url": "https://api.example.com", "ip": "10.0.0.1:3128", "target": "general"}
```

Use JSON format in Docker and Kubernetes deployments.

## Writing to a file

```bash theme={}
proxy-hopper run --config config.yaml --log-file /var/log/proxy-hopper.log
```

Or via config:

```yaml theme={}
server:
  logFile: /var/log/proxy-hopper.log
```

If omitted, logs are written to stderr.

## Recommended settings by environment

| Environment          | Level   | Format |
| -------------------- | ------- | ------ |
| Local development    | `DEBUG` | `text` |
| Docker (single host) | `INFO`  | `json` |
| Kubernetes           | `INFO`  | `json` |
| Debugging production | `DEBUG` | `json` |