# Supabase Logs

Stream logs from all 9 Supabase services into Gonzo for real-time terminal analysis — API gateway, Postgres, Auth, Storage, Realtime, Edge Functions, PostgREST, Supavisor, and function edge logs.

### How It Works

Supabase doesn't expose a streaming log API. The included poller script (`supabase-log-poller.sh`) polls the Management API's SQL-based log query endpoint, normalizes the deeply nested metadata from each service into flat JSONL, and pipes the result into Gonzo. One script covers all 9 sources.

### Quick Start

```bash
# Download the poller script
curl -fsSL https://raw.githubusercontent.com/control-theory/gonzo/main/scripts/supabase-log-poller.sh -o supabase-log-poller.sh
chmod +x supabase-log-poller.sh

# Set credentials
export SUPABASE_ACCESS_TOKEN="sbp_your_token"
export SUPABASE_PROJECT_REF="your_project_ref"

# Pipe into Gonzo
./supabase-log-poller.sh | gonzo
```

### Prerequisites

* Gonzo installed
* `jq` installed (`brew install jq`)
* A Supabase project (free tier works)

### Credentials

**Project Ref** — Found in your dashboard URL (`https://supabase.com/dashboard/project/<ref>`) or under Settings → General.

**Personal Access Token** — Generate at supabase.com/dashboard/account/tokens. Starts with `sbp_`.

### Log Sources

| Source               | Service              | What it captures                              |
| -------------------- | -------------------- | --------------------------------------------- |
| `edge_logs`          | `api-gateway`        | Every API request through the Cloudflare edge |
| `postgres_logs`      | `postgres`           | Queries, connections, errors, pgAudit         |
| `auth_logs`          | `gotrue`             | Sign-ups, logins, token ops, auth errors      |
| `storage_logs`       | `storage`            | Uploads, downloads, bucket operations         |
| `realtime_logs`      | `realtime`           | WebSocket connections, Phoenix events         |
| `function_logs`      | `edge-function/<id>` | Edge Function console output                  |
| `function_edge_logs` | `edge-function/<id>` | Edge Function network request/response        |
| `postgrest_logs`     | `postgrest`          | REST API server lifecycle                     |
| `supavisor_logs`     | `pooler`             | Connection pooler activity                    |

### Usage Patterns

Suppress poller status messages:

```bash
./supabase-log-poller.sh 2>/dev/null | gonzo
```

Write to file (supports auto-rotation at 100MB):

```bash
./supabase-log-poller.sh -o /tmp/supabase-logs/all.jsonl
gonzo -f /tmp/supabase-logs/all.jsonl --follow
```

Faster polling:

```bash
POLL_INTERVAL=10 ./supabase-log-poller.sh | gonzo
```

With AI analysis:

```bash
export OPENAI_API_KEY="sk-your-key"
./supabase-log-poller.sh 2>/dev/null | gonzo --ai-model="gpt-4"
```

### Filtering in Gonzo

Press `/` to filter. Useful patterns:

| Filter          | What you'll see       |
| --------------- | --------------------- |
| `edge_logs`     | API gateway requests  |
| `postgres_logs` | Database activity     |
| `auth_logs`     | Authentication events |
| `gotrue`        | Auth service by name  |
| `ERROR`         | Server errors (5xx)   |
| `WARN`          | Client errors (4xx)   |

### Rate Limits

The Management API allows 120 requests/min per project. The poller makes 9 requests per cycle. At the default 30s interval that's 18 req/min — well within limits. Don't set `POLL_INTERVAL` below 10s.

| POLL\_INTERVAL | Requests/min | Risk                |
| -------------- | ------------ | ------------------- |
| 30s (default)  | 18           | ✅ Safe              |
| 15s            | 36           | ✅ Safe              |
| 10s            | 54           | ⚠️ Use with caution |

### Log Propagation Delay

Supabase logs are ingested via Logflare and typically take 30–90 seconds to appear in the API. The poller's time window overlaps by 5 seconds to avoid gaps.

***

**Time to complete:** 10–15 minutes | **Prerequisites:** Supabase project, `jq`, Gonzo installed | **Full guide:** [`guides/SUPABASE_USAGE_GUIDE.md`](https://github.com/control-theory/gonzo/blob/main/guides/SUPABASE_USAGE_GUIDE.md)