# Railway Logs

Stream logs from Railway services into Gonzo with zero configuration. Railway's CLI outputs JSON over WebSocket. Gonzo auto-detects the format — no poller, no normalizer, no `jq` transforms.

### Quick Start

```bash
railway login
railway link
railway logs --json | gonzo
```

That's it. Works on all Railway plans (Trial, Hobby, Pro).

### Prerequisites

* Gonzo installed
* [Railway CLI](https://docs.railway.com/guides/cli) installed (`brew install railway`)
* A Railway project with at least one deployed service

### Log Types

| Log type       | CLI flag           | Gonzo compatible | What it captures                                 |
| -------------- | ------------------ | ---------------- | ------------------------------------------------ |
| **Deployment** | `--json` (default) | ✅                | App stdout/stderr                                |
| **Build**      | `--build --json`   | ✅                | Dependency installs, compilation, image creation |
| **HTTP**       | Dashboard only     | ❌                | Edge proxy request logs (not available via CLI)  |

### Usage Patterns

**Real-time streaming** (WebSocket, no rate limits):

```bash
railway logs --json | gonzo
```

**Fetch last N lines:**

```bash
railway logs --json --lines 100 | gonzo
```

**Time range:**

```bash
railway logs --json --since 1h | gonzo
```

**Build logs after a failed deploy:**

```bash
railway logs --build --json --lines 100 | gonzo
```

**Filter at source:**

```bash
railway logs --json --filter "@level:error" | gonzo
```

**Write to file:**

```bash
railway logs --json > /tmp/railway-logs.jsonl &
gonzo -f /tmp/railway-logs.jsonl --follow
```

**With local AI (logs never leave your machine):**

```bash
export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"
railway logs --json | gonzo
```

### Multi-Service Projects

Stream from a specific service:

```bash
railway logs --json --service <service-id> | gonzo
```

### Rate Limits

**Streaming** (`--json | gonzo`) uses WebSocket — **not rate limited**. This is the recommended mode.

**Fetch mode** (`--lines`, `--since`) uses the GraphQL API:

| Plan       | Requests/hour |
| ---------- | ------------- |
| Free/Trial | 100           |
| Hobby      | 1,000         |
| Pro        | 10,000        |

**Platform cap:** 500 log lines/second per replica. Excess is silently dropped. Use minified JSON (not pretty-printed) to stay under the limit.

### Structured Logging Tips

If your app emits structured JSON to stdout, Railway preserves it as-is. Non-JSON is wrapped in `{"message":"...","level":"..."}`. Stderr output is auto-tagged as `level: "error"` — a common gotcha for Python's `logging` library which defaults to stderr.

**Time to complete:** 5 minutes **Prerequisites:** Railway CLI, Gonzo installed **Full guide:** [`guides/RAILWAY_USAGE_GUIDE.md`](https://github.com/control-theory/gonzo/blob/main/guides/RAILWAY_USAGE_GUIDE.md)