# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/supabase-logs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.