> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/supabase-logs.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.