mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
docs: split Studio logs from ClickHouse log queries (#49501)
<!-- CURSOR_AGENT_PR_BODY_BEGIN --> ## Stack Draft stack extracted from `docs/monitoring`. Merge bottom-up. Troubleshooting / debugging-guide rewrite is out of scope. 1. #49503 move inspect and advisors 2. **#49501** split Studio logs from ClickHouse queries ← **this PR** 3. #49500 treat reports as signal dashboards 4. #49502 add Observe the data hub 5. #49506 add agent setup components 6. #49504 add hire-an-agent templates 7. #49505 restructure observability nav and overview ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Second layer in the observability stack. ## What is the current behavior? `/guides/monitoring-and-debugging/logs` mixes the Studio Logs UI with ClickHouse query syntax, sources, and recording extra events. ## What is the new behavior? - Logs is the Studio interface guide (filters, log types, inspecting a row) - Query and filter logs (`advanced-log-filtering`) owns ClickHouse SQL, sources, MCP/API/CLI access, and recording extra Postgres/API/Realtime events - Log field reference explains `log_attributes` query paths - Nav labels and cross-links follow the new titles ## Additional context Forward links to the later Observe the data hub are added in #49502. ## Self-review - Existing `#querying-with-the-logs-explorer` and `#configuring-pgauditlog` anchors now live on Query and filter logs - Debugging-guide links that pointed at the old Logs Explorer heading were retargeted so they still resolve <!-- CURSOR_AGENT_PR_BODY_END --> <div><a href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com> Co-authored-by: Nik Richers <nik@validmind.ai>
This commit is contained in:
13 files changed
+347
-472
No files matched your search
@@ -3034,11 +3034,11 @@ export const telemetry: NavMenuConstant = {
|
||||
url: '/guides/monitoring-and-debugging/debugging' as `/${string}`,
|
||||
},
|
||||
{
|
||||
name: 'Logging',
|
||||
name: 'Logs',
|
||||
url: '/guides/monitoring-and-debugging/logs' as `/${string}`,
|
||||
},
|
||||
{
|
||||
name: 'Advanced log filtering',
|
||||
name: 'Query and filter logs',
|
||||
url: '/guides/monitoring-and-debugging/advanced-log-filtering' as `/${string}`,
|
||||
},
|
||||
{
|
||||
|
||||
@@ -56,7 +56,7 @@ The Supabase MCP server provides tools organized into feature groups. All groups
|
||||
|
||||
### Debugging
|
||||
|
||||
- `query_logs` - Run a read-only SQL query against project logs to filter, aggregate, or join across log fields
|
||||
- `query_logs` - Run a read-only SQL query against project logs to filter, aggregate, or join across log fields. See [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering).
|
||||
- `get_advisors` - Get security and performance advisors
|
||||
|
||||
### Development
|
||||
|
||||
@@ -233,28 +233,3 @@ group by hour, path
|
||||
order by hour desc
|
||||
limit 100;
|
||||
```
|
||||
|
||||
### Find data API request from specific authenticated user
|
||||
|
||||
```sql
|
||||
select
|
||||
timestamp,
|
||||
event_message,
|
||||
log_attributes['request.headers.cf_connecting_ip'] as requesters_ip,
|
||||
log_attributes['request.url'] as request_url,
|
||||
log_attributes['request.method'] as request_method,
|
||||
log_attributes['request.sb.jwt.authorization.payload.subject'] as user_id,
|
||||
log_attributes['request.sb.jwt.apikey.payload.role'] as apikey_role,
|
||||
log_attributes['request.sb.jwt.authorization.payload.role'] as authorization_token_role,
|
||||
log_attributes['request.headers.user_agent'] as user_agent,
|
||||
log_attributes['request.cf.city'] as city,
|
||||
log_attributes['request.cf.country'] as country,
|
||||
log_attributes['request.cf.postalCode'] as postalCode
|
||||
from logs
|
||||
where
|
||||
source = 'edge_logs'
|
||||
and match(log_attributes['request.path'], '^/rest/v1/')
|
||||
and log_attributes['request.sb.jwt.authorization.payload.subject'] = 'SOME_USER_ID' -- <---ADD USER_ID from auth.users table
|
||||
order by timestamp desc
|
||||
limit 100;
|
||||
```
|
||||
@@ -1,23 +1,18 @@
|
||||
---
|
||||
title: 'Advanced Log Querying and Filtering'
|
||||
description: 'Query and filter logs with regular expressions'
|
||||
title: 'Query and filter logs'
|
||||
description: 'Query project logs from Studio, MCP, the API, or a script. Record extra Postgres, API, and Realtime events.'
|
||||
---
|
||||
|
||||
The [Logs Explorer](/dashboard/project/_/logs-explorer) exposes logs from each part of the Supabase stack, which you can query and filter using SQL.
|
||||
This guide explains how to query project logs and how to record extra events. The same ClickHouse SQL runs in the [Logs Explorer](/dashboard/project/_/logs/explorer), the MCP [`query_logs`](/docs/guides/ai-tools/mcp) tool, and the [Management API](/docs/reference/api/v1-get-project-logs). Filter events without SQL in [Logs](/docs/guides/monitoring-and-debugging/logs) in Studio. From a terminal, call the Management API; the CLI inspects the database rather than ClickHouse logs.
|
||||
|
||||
|
||||
Use this page to:
|
||||
|
||||
You can access the following log sources from the **Sources** drop-down:
|
||||
- Query logs from [Studio](#studio), [MCP](#mcp), the [API](#api), or a [script](#cli)
|
||||
- Pick a [`source`](#logs-explorer) for the layer that reported the error
|
||||
- Record extra [API](#working-with-api-logs), [Postgres](#logging-postgres-queries), and [Realtime](#logging-realtime-connections) events
|
||||
- Write [ClickHouse SQL](#querying-with-the-logs-explorer)
|
||||
|
||||
- `auth_logs`: GoTrue server logs, containing authentication/authorization activity.
|
||||
- `edge_logs`: Edge network logs, containing request and response metadata retrieved from Cloudflare.
|
||||
- `function_edge_logs`: Edge network logs for only edge functions, containing network requests and response metadata for each execution.
|
||||
- `function_logs`: Function internal logs, containing any `console` logging from within the edge function.
|
||||
- `postgres_logs`: Postgres database logs, containing statements executed by connected applications.
|
||||
- `realtime_logs`: Realtime server logs, containing client connection information.
|
||||
- `storage_logs`: Storage server logs, containing object upload and retrieval information.
|
||||
|
||||
The Logs Explorer runs on ClickHouse. Every log line from every source is one row in a single `logs` table, tagged by a `source` column. Structured fields live in a `log_attributes` map, and the raw line is in `event_message`. Filter by `source` to scope a query to one service.
|
||||
Every log line is one row in a single `logs` table, tagged by a `source` column. Structured fields live in a `log_attributes` map, and the raw line is in `event_message`. Filter by `source` to scope a query to one service.
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
@@ -25,9 +20,259 @@ ClickHouse has been the default engine since June 2026. Projects created before
|
||||
|
||||
</Admonition>
|
||||
|
||||
On hosted projects, prefer `query_logs` over `get_logs`. `get_logs` returns a service's recent logs without SQL; it remains the option for local and self-hosted projects.
|
||||
|
||||
## Query from Studio, MCP, the API, or the CLI
|
||||
|
||||
### Studio [#studio]
|
||||
|
||||
Open [Logs](/dashboard/project/_/logs) to filter and inspect events. Open the [Logs Explorer](/dashboard/project/_/logs/explorer) to run ClickHouse SQL. See [Logs](/docs/guides/monitoring-and-debugging/logs) for the unified Logs interface.
|
||||
|
||||
### MCP [#mcp]
|
||||
|
||||
On hosted projects, call [`query_logs`](/docs/guides/ai-tools/mcp) with the same SQL as this guide. Keep the connection project-scoped and read-only.
|
||||
|
||||
### API [#api]
|
||||
|
||||
Pass ClickHouse SQL in the `sql` parameter of the [Management API logs endpoint](/docs/reference/api/v1-get-project-logs). Unless you pass `sql`, that endpoint queries `edge_logs` only. Supply `iso_timestamp_start` and `iso_timestamp_end`; the range must be 24 hours or less.
|
||||
|
||||
### CLI [#cli]
|
||||
|
||||
The Supabase CLI does not query ClickHouse logs. Call the [Management API](/docs/reference/api/v1-get-project-logs) from a script, or use [`supabase inspect db`](/docs/guides/monitoring-and-debugging/inspect) for database diagnostics.
|
||||
|
||||
## Sources [#logs-explorer]
|
||||
|
||||
Filter by `source` to query one service. The Logs Explorer **Sources** drop-down lists these values.
|
||||
|
||||
Pick the source for the layer that reported the error. A request hits the API gateway first, then one service, then the pooler and Postgres. The layer that _reports_ an error is often not the layer that _caused_ it. When two sources could fit, start closer to the database.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Client --> Gateway["API gateway — edge_logs"]
|
||||
Gateway --> PostgREST
|
||||
Gateway --> Auth
|
||||
Gateway --> Storage
|
||||
Gateway --> Realtime
|
||||
PostgREST --> Pooler["Pooler — supavisor_logs, pgbouncer_logs"]
|
||||
Auth --> Pooler
|
||||
Storage --> Pooler
|
||||
Pooler --> Postgres["Postgres — postgres_logs"]
|
||||
```
|
||||
|
||||
Edge Functions sit outside that path: `function_edge_logs` is the HTTP request to the function, and `function_logs` is `console` output from inside it.
|
||||
|
||||
A permission error or an empty result at the API is often row-level security in `postgres_logs`.
|
||||
|
||||
| `source` | Events |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `edge_logs` | HTTP requests through the API gateway, including REST and GraphQL |
|
||||
| `postgres_logs` | Database queries, SQLSTATE, RLS, and functions |
|
||||
| `postgrest_logs` | PostgREST process logs. Low-signal; `PGRST*` evidence usually lives in `edge_logs` and `postgres_logs` |
|
||||
| `auth_logs` | Auth server: login, JWT, OAuth, email |
|
||||
| `auth_audit_logs` | Auth audit events |
|
||||
| `storage_logs` | Storage API: uploads and object access |
|
||||
| `realtime_logs` | Realtime server: channels, presence, broadcast |
|
||||
| `function_edge_logs` | HTTP request and response for an Edge Function invocation |
|
||||
| `function_logs` | `console` output from inside an Edge Function |
|
||||
| `supavisor_logs` | Shared pooler: pooling and timeouts |
|
||||
| `pgbouncer_logs` | Dedicated pooler |
|
||||
| `pg_upgrade_logs` | Database version upgrade |
|
||||
|
||||
For `postgres_logs`, statement text and error detail live in `event_message`. `parsed.query` and `parsed.detail` are usually empty.
|
||||
|
||||
For API Load Balancer traffic, the upstream database is `log_attributes['load_balancer_redirect_identifier']`.
|
||||
|
||||
See the [Logs field reference](/docs/guides/monitoring-and-debugging/log-field-reference) for the ClickHouse field names on each source.
|
||||
|
||||
## Working with API logs [#working-with-api-logs]
|
||||
|
||||
API Gateway logs run through Cloudflare and include Cloudflare metadata on the request.
|
||||
|
||||
### Allowed headers
|
||||
|
||||
A strict list of request and response headers are permitted in the API logs. Request and response headers will still be received by the server(s) and client(s), but will not be attached to the API logs generated.
|
||||
|
||||
Request headers:
|
||||
|
||||
- `accept`
|
||||
- `cf-connecting-ip`
|
||||
- `cf-ipcountry`
|
||||
- `host`
|
||||
- `user-agent`
|
||||
- `x-forwarded-proto`
|
||||
- `referer`
|
||||
- `content-length`
|
||||
- `x-real-ip`
|
||||
- `x-client-info`
|
||||
- `x-forwarded-user-agent`
|
||||
- `range`
|
||||
- `prefer`
|
||||
|
||||
Response headers:
|
||||
|
||||
- `cf-cache-status`
|
||||
- `cf-ray`
|
||||
- `content-location`
|
||||
- `content-range`
|
||||
- `content-type`
|
||||
- `content-length`
|
||||
- `date`
|
||||
- `transfer-encoding`
|
||||
- `x-kong-proxy-latency`
|
||||
- `x-kong-upstream-latency`
|
||||
- `sb-gateway-mode`
|
||||
- `sb-gateway-version`
|
||||
|
||||
### Additional request metadata
|
||||
|
||||
To attach additional metadata to a request, it is recommended to use the `User-Agent` header for purposes such as device or version identification.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
node MyApp/1.2.3 (device-id:abc123)
|
||||
Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 MyApp/1.2.3 (Foo v1.3.2; Bar v2.2.2)
|
||||
```
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
Do not log Personal Identifiable Information (PII) within the `User-Agent` header, to avoid infringing data protection privacy laws. Overly fine-grained and detailed user agents may allow fingerprinting and identification of the end user through PII.
|
||||
|
||||
</Admonition>
|
||||
|
||||
## Logging Postgres connections [#logging-postgres-connections]
|
||||
|
||||
Postgres can log connection lifecycle events to your project's Postgres logs, for example when a client connects or authenticates. By default, Supabase sets `log_connections` to off for new projects and you must enable it first.
|
||||
|
||||
To enable connection logging for audit or compliance, see [Postgres connection logging](/docs/guides/platform/postgres-connection-logging).
|
||||
|
||||
In Logs, connection lifecycle messages are included when the Postgres log type is selected. Clear **Connection logs** under Postgres to hide them.
|
||||
|
||||
## Logging Postgres queries [#logging-postgres-queries]
|
||||
|
||||
To enable query logs for other categories of statements:
|
||||
|
||||
1. [Enable the pgAudit extension](/dashboard/project/_/database/extensions).
|
||||
2. Configure `pgaudit.log` (see below). Perform a fast reboot if needed.
|
||||
3. View your query logs in [Logs](/dashboard/project/_/logs). Filter **Log Type** to Postgres.
|
||||
|
||||
### Configuring `pgaudit.log` [#configuring-pgauditlog]
|
||||
|
||||
The stored value under `pgaudit.log` determines the classes of statements that are logged by [pgAudit extension](https://www.pgaudit.org/). Refer to the pgAudit documentation for the [full list of values](https://github.com/pgaudit/pgaudit/blob/master/README.md#pgauditlog).
|
||||
|
||||
To enable logging for function calls/do blocks, writes, and DDL statements for a single session, execute the following within the session:
|
||||
|
||||
```sql
|
||||
-- temporary single-session config update
|
||||
set pgaudit.log = 'function, write, ddl';
|
||||
```
|
||||
|
||||
To _permanently_ set a logging configuration (beyond a single session), execute the following, then perform a fast reboot:
|
||||
|
||||
```sql
|
||||
-- equivalent permanent config update.
|
||||
alter role postgres set pgaudit.log to 'function, write, ddl';
|
||||
```
|
||||
|
||||
To help with debugging, we recommend adjusting the log scope to only relevant statements as having too wide of a scope would result in a lot of noise in your Postgres logs.
|
||||
|
||||
Note that in the above example, the role is set to `postgres`. To log user traffic flowing through the [HTTP APIs](/docs/guides/api#rest-api-overview), which use PostgREST, set your configuration values for the `authenticator`.
|
||||
|
||||
```sql
|
||||
-- for API-related logs
|
||||
alter role authenticator set pgaudit.log to 'write';
|
||||
```
|
||||
|
||||
By default, the log level will be set to `log`. To view other levels, run the following:
|
||||
|
||||
```sql
|
||||
-- adjust log level
|
||||
alter role postgres set pgaudit.log_level to 'info';
|
||||
alter role postgres set pgaudit.log_level to 'debug5';
|
||||
```
|
||||
|
||||
Note that as per the pgAudit [log_level documentation](https://github.com/pgaudit/pgaudit/blob/master/README.md#pgauditlog_level), `error`, `fatal`, and `panic` are not allowed.
|
||||
|
||||
To reset system-wide settings, execute the following, then perform a fast reboot:
|
||||
|
||||
```sql
|
||||
-- resets stored config.
|
||||
alter role postgres reset pgaudit.log
|
||||
```
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
If any permission errors are encountered when executing `alter role postgres ...`, it is likely that your project has yet to receive the patch to the latest version of [supautils](https://github.com/supabase/supautils), which is currently being rolled out.
|
||||
|
||||
</Admonition>
|
||||
|
||||
### `RAISE`d log messages in Postgres
|
||||
|
||||
Messages that are manually logged via `RAISE INFO`, `RAISE NOTICE`, `RAISE WARNING`, and `RAISE LOG` are shown in Postgres Logs. Note that only messages at or above your logging level are shown. Syncing of messages to Postgres Logs may take a few minutes.
|
||||
|
||||
If your logs aren't showing, check your logging level by running:
|
||||
|
||||
```sql
|
||||
show log_min_messages;
|
||||
```
|
||||
|
||||
Note that `LOG` is a higher level than `WARNING` and `ERROR`, so if your level is set to `LOG`, you will not see `WARNING` and `ERROR` messages.
|
||||
|
||||
### Limits and caveats
|
||||
|
||||
- Postgres log events on the Supabase Platform are limited to 100,000 characters. If a log event exceeds this limit, it will be truncated. This does not apply to self-hosting.
|
||||
- Internal connection logs to Postgres within the Supabase Platform by internal services are not logged. This does not apply to self-hosting.
|
||||
|
||||
## Logging realtime connections [#logging-realtime-connections]
|
||||
|
||||
Realtime doesn't log new WebSocket connections or Channel joins by default. Enable connection logging per client by including an `info` `log_level` parameter when instantiating the Supabase client.
|
||||
|
||||
```javascript
|
||||
import { createClient } from '@supabase/supabase-js'
|
||||
|
||||
const options = {
|
||||
realtime: {
|
||||
params: {
|
||||
log_level: 'info',
|
||||
},
|
||||
},
|
||||
}
|
||||
const supabase = createClient('https://xyzcompany.supabase.co', 'sb_publishable_...', options)
|
||||
```
|
||||
|
||||
## Querying logs [#querying-with-the-logs-explorer]
|
||||
|
||||
Read fields with bracket access, keeping the full dotted key, for example `log_attributes['request.path']` rather than `path`. Wrap numeric values in `toInt32OrZero(...)`, which returns `0` for a missing or non-numeric value. Use `count()` rather than `count(*)`.
|
||||
|
||||
For example, to find failing API requests:
|
||||
|
||||
```sql
|
||||
select timestamp,
|
||||
toInt32OrZero(log_attributes['response.status_code']) as status,
|
||||
log_attributes['request.path'] as path
|
||||
from logs
|
||||
where source = 'edge_logs'
|
||||
and toInt32OrZero(log_attributes['response.status_code']) >= 400
|
||||
order by timestamp desc
|
||||
limit 100;
|
||||
```
|
||||
|
||||
For example, to find a specific Postgres SQLSTATE (`42501` permission denied, `42P01` relation missing, `23505` duplicate key):
|
||||
|
||||
```sql
|
||||
select timestamp, log_attributes['parsed.user_name'] as role, event_message
|
||||
from logs
|
||||
where source = 'postgres_logs'
|
||||
and log_attributes['parsed.sql_state_code'] = '42501'
|
||||
order by timestamp desc
|
||||
limit 100;
|
||||
```
|
||||
|
||||
The Management API accepts this SQL in the `sql` parameter. Unless you pass `sql`, that endpoint queries `edge_logs` only. Supply `iso_timestamp_start` and `iso_timestamp_end`; the range must be 24 hours or less.
|
||||
|
||||
## Timestamp display and behavior
|
||||
|
||||
The `timestamp` column is a `DateTime64` value in UTC, formatted as an ISO-8601 string like `2026-06-22T09:34:06.215000`. You can order and compare it directly, so no conversion function is needed. In the Logs Explorer the selected time range is applied for you, so you rarely need to filter on `timestamp` by hand.
|
||||
The `timestamp` column is a `DateTime64` value in UTC, formatted as an ISO-8601 string like `2026-06-22T09:34:06.215000`. You can order and compare it directly, so no conversion function is needed. In the Logs Explorer the selected time range is applied for you, so you rarely need to filter on `timestamp` by hand. MCP and the Management API require an explicit time range.
|
||||
|
||||
```sql
|
||||
select timestamp, event_message
|
||||
@@ -99,6 +344,16 @@ from logs
|
||||
where source = 'edge_logs';
|
||||
```
|
||||
|
||||
3. **Query one source at a time.**
|
||||
|
||||
Identify which service owns the problem from the error or status code first, then query only that source. Scanning every source at once buries the signal you need and scans far more data than the investigation requires.
|
||||
|
||||
4. **Follow a request across sources with an anchor.** Once a query gives you an anchor such as a timestamp, request id, or SQL state, filter the adjacent source by that anchor to correlate the request across layers (for example `edge_logs` to `postgres_logs`), instead of re-scanning each source from scratch.
|
||||
|
||||
5. **Reference only fields you have confirmed.**
|
||||
|
||||
A misspelled or non-existent field name either errors or silently returns nothing, which leaves a working query look empty. Confirm field names in the [Logs field reference](/docs/guides/monitoring-and-debugging/log-field-reference), or select `event_message` and inspect a sample row first.
|
||||
|
||||
## Examples and templates
|
||||
|
||||
The Logs Explorer includes **Templates** (available in the Templates tab or the dropdown in the Query tab) to help you get started.
|
||||
@@ -140,12 +395,6 @@ where source = 'postgres_logs'
|
||||
limit 100;
|
||||
```
|
||||
|
||||
## Expanding results
|
||||
|
||||
Logs returned by queries may be difficult to read in table format. Double-click a row to expand the result into more readable JSON:
|
||||
|
||||
|
||||
|
||||
## Filtering with [regular expressions](https://en.wikipedia.org/wiki/Regular_expression)
|
||||
|
||||
Use the ClickHouse [`match` function](https://clickhouse.com/docs/sql-reference/functions/string-search-functions#match) for regular expressions. In its most basic form, it checks whether a pattern is present in a column.
|
||||
|
||||
@@ -12,7 +12,7 @@ An AI agent can work through this loop for you, but only if it can read your pro
|
||||
|
||||
Debugging with an agent needs two things:
|
||||
|
||||
- The [Supabase MCP server](/docs/guides/ai-tools/mcp) provides the tools this guide relies on: `get_logs` for a per-service log dump, `query_logs` to run read-only SQL against your logs for filtering and aggregation (see [Querying with the Logs Explorer](/docs/guides/monitoring-and-debugging/logs#querying-with-the-logs-explorer) for the ClickHouse SQL syntax it accepts), `get_advisors` for security and performance findings, and `execute_sql` to inspect your schema and policies.
|
||||
- The [Supabase MCP server](/docs/guides/ai-tools/mcp) provides the tools this guide relies on: `get_logs` for a per-service log dump, `query_logs` to run read-only SQL against your logs for filtering and aggregation (see [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering) for the ClickHouse SQL syntax it accepts), `get_advisors` for security and performance findings, and `execute_sql` to inspect your schema and policies.
|
||||
- The [Supabase agent skill](/docs/guides/ai-tools/ai-skills) teaches the agent this workflow: locate the failing layer, gather evidence from the matching log source, and verify the fix by re-running the operation that failed.
|
||||
|
||||
Install both in one step with the [Supabase plugin for AI coding agents](/docs/guides/ai-tools/plugins). Connecting an agent to your project carries security risks, so read the [MCP security best practices](/docs/guides/ai-tools/mcp#security-risks) first.
|
||||
@@ -63,7 +63,7 @@ When a query comes up empty, widen along an anchor, such as a timestamp, request
|
||||
|
||||
A wide, unfiltered query across every source buries the one line you need and, on paid projects, costs more in scanned data.
|
||||
|
||||
The [Logging guide](/docs/guides/monitoring-and-debugging/logs) covers the Logs Explorer, the available log sources, and how to write queries against them.
|
||||
The [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering) guide covers the Logs Explorer, the available log sources, and how to write queries against them.
|
||||
|
||||
## Find the guide for your symptom
|
||||
|
||||
|
||||
@@ -4,7 +4,9 @@ title: 'Logs field reference'
|
||||
description: 'Supabase Logs field reference'
|
||||
---
|
||||
|
||||
Refer to the full field reference for each available source below. To access each nested key, you need to perform the [necessary unnesting joins](/docs/guides/monitoring-and-debugging/advanced-log-filtering#unnesting-arrays)
|
||||
Use this reference to find the fields available for each log source. Query `id`, `timestamp`, `event_message`, and `source` as top-level columns. Other structured fields are keys in the `log_attributes` map: drop the `metadata.` prefix shown in the source schema and keep the rest of the dotted path.
|
||||
|
||||
For example, the schema path `metadata.request.cf.country` is queried as `log_attributes['request.cf.country']`. See [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering) for complete ClickHouse examples.
|
||||
|
||||
<SharedData data="logConstants">
|
||||
{(logConstants) => (
|
||||
@@ -14,16 +16,22 @@ Refer to the full field reference for each available source below. To access eac
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th className="font-bold">Path</th>
|
||||
<th className="font-bold">Schema path</th>
|
||||
<th className="font-bold">ClickHouse query field</th>
|
||||
<th className="font-bold">Type</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{schema.fields
|
||||
.sort((a, b) => a.path - b.path)
|
||||
.sort((a, b) => a.path.localeCompare(b.path))
|
||||
.map((field) => (
|
||||
<tr key={field.path}>
|
||||
<td className="font-mono">{field.path}</td>
|
||||
<td className="font-mono">
|
||||
{field.path.startsWith('metadata.')
|
||||
? `log_attributes['${field.path.slice('metadata.'.length)}']`
|
||||
: field.path}
|
||||
</td>
|
||||
<td className="font-mono">{field.type}</td>
|
||||
</tr>
|
||||
))}
|
||||
|
||||
@@ -1,417 +1,81 @@
|
||||
---
|
||||
id: 'logs'
|
||||
title: 'Logging'
|
||||
description: 'Getting started with Supabase Log Browser'
|
||||
title: 'Logs'
|
||||
description: 'Inspect project log events in the unified Logs view in Studio'
|
||||
---
|
||||
|
||||
The Supabase Platform includes a Logs Explorer that allows log tracing and debugging. Log retention is based on your [project's pricing plan](/pricing). For details on how Logs usage is billed, see [Manage Logs usage](/docs/guides/platform/manage-your-usage/logs).
|
||||
This guide explains how to inspect project logs in Studio. Log retention is based on your [project's pricing plan](/pricing). For details on how Logs usage is billed, see [Manage Logs usage](/docs/guides/platform/manage-your-usage/logs).
|
||||
|
||||
Use this page to filter and inspect events in [Logs](#product-logs). To query the same data with SQL from Studio, MCP, the API, or a script, or to record extra Postgres, API, and Realtime events, see [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering).
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
If you are debugging a specific error or unexpected behavior, start with the [Debugging guide](/docs/guides/monitoring-and-debugging/debugging) — it routes you to the right log source based on your error code or symptom before you open the Logs Explorer.
|
||||
If you already have a specific error, start at [Find the guide for your symptom](/docs/guides/monitoring-and-debugging/debugging#find-the-guide-for-your-symptom). If you are checking whether the project is healthy, start with the [debugging guide](/docs/guides/monitoring-and-debugging/debugging).
|
||||
|
||||
</Admonition>
|
||||
|
||||
## Product logs
|
||||
## Filter and inspect events [#product-logs]
|
||||
|
||||
Supabase provides a logging interface specific to each product. You can use regular expressions for keywords and patterns to search log event messages. You can also export and download the log events matching your query as a spreadsheet.
|
||||
Open [Logs](/dashboard/project/_/logs). The page shows a timeline of success, warning, and error events, a filterable table, and a detail panel when you select a row.
|
||||
|
||||
If you don't select a log type, Logs queries **Postgres** and **API Gateway** events. Selecting log types replaces that default set.
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
For regular expression filtering, structured-field queries, and field discovery techniques, see [Advanced log filtering](/docs/guides/monitoring-and-debugging/advanced-log-filtering).
|
||||
For regular expression filtering, structured-field queries, and field discovery, see [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering).
|
||||
|
||||
</Admonition>
|
||||
|
||||
{/* <!-- To update screenshots, ensure that at least one log line is selected to display the metadata. Can use meme.town as an example. --> */}
|
||||
### Filter logs
|
||||
|
||||
<Tabs
|
||||
scrollable
|
||||
size="small"
|
||||
type="underlined"
|
||||
defaultActiveId="api"
|
||||
queryGroup="product"
|
||||
>
|
||||
<TabPanel id="api" label="API">
|
||||
1. Open [Logs](/dashboard/project/_/logs).
|
||||
2. Set the **Time Range** in the sidebar.
|
||||
3. Select one or more **Log Type** values. Nested toggles under API Gateway include or exclude Auth, Storage, and PostgREST request paths. The nested toggle under Postgres shows or hides connection logs.
|
||||
4. Optionally filter by **Level**, **Status**, **Method**, **Pathname**, or **Event message**. Type in the filter bar to search event messages.
|
||||
5. Optionally filter by **User**. This filter only matches Auth and Postgres events.
|
||||
|
||||
[API logs](/dashboard/project/_/logs/edge-logs) show all network requests and response for the REST and GraphQL [APIs](../../guides/database/api). If [Read Replicas](/docs/guides/platform/read-replicas) are enabled, logs are automatically filtered between databases as well as the [API Load Balancer](/docs/guides/platform/read-replicas#api-load-balancer) endpoint. Logs for a specific endpoint can be toggled with the `Source` button on the upper-right section of the dashboard.
|
||||
Refresh the table, hide columns, download matching rows as CSV or JSON, or turn on live mode to stream new events.
|
||||
|
||||
When viewing logs originating from the API Load Balancer endpoint, the upstream database or the one that eventually handles the request can be found under the `Redirect Identifier` field. This is equivalent to `metadata.load_balancer_redirect_identifier` when querying the underlying logs.
|
||||
### Log types
|
||||
|
||||
|
||||
Selecting a log type in Studio queries the matching ClickHouse `source`. For the `source` names to use in SQL, see [Sources](/docs/guides/monitoring-and-debugging/advanced-log-filtering#logs-explorer).
|
||||
|
||||
</TabPanel>
|
||||
<TabPanel id="postgres" label="Postgres">
|
||||
| Log type | Events |
|
||||
| ------------- | ----------------------------------------------------------------- |
|
||||
| API Gateway | HTTP requests through the API gateway, including REST and GraphQL |
|
||||
| Postgres | Database queries and activity |
|
||||
| PostgREST | PostgREST server logs |
|
||||
| Auth | Auth server logs |
|
||||
| Storage | Storage API server logs |
|
||||
| Edge Function | Edge Function HTTP invocations and `console` output |
|
||||
| Realtime | Realtime server logs |
|
||||
| Supavisor | Connection pooler logs |
|
||||
| PgBouncer | PgBouncer logs |
|
||||
|
||||
[Postgres logs](/dashboard/project/_/logs/postgres-logs) show queries and activity for your [database](../../guides/database). If [Read Replicas](/docs/guides/platform/read-replicas) are enabled, logs are automatically filtered between databases. Logs for a specific database can be toggled with the `Source` button on the upper-right section of the dashboard.
|
||||
Selecting **API Gateway** is not the same as selecting **Auth**, **Storage**, or **PostgREST**. The nested API Gateway toggles filter HTTP paths on the gateway. The Auth, Storage, and PostgREST log types query those services' own logs.
|
||||
|
||||
|
||||
### Postgres [#postgres]
|
||||
|
||||
</TabPanel>
|
||||
<TabPanel id="auth" label="Auth">
|
||||
Postgres logs show queries and activity for your database. Connection lifecycle events appear here when [connection logging](/docs/guides/monitoring-and-debugging/advanced-log-filtering#logging-postgres-connections) is enabled. They are included by default; clear **Connection logs** under the Postgres log type to hide them.
|
||||
|
||||
[Auth logs](/dashboard/project/_/logs/auth-logs) show all server logs for your [Auth usage](../../guides/auth).
|
||||
To record additional statement classes, see [Logging Postgres queries](/docs/guides/monitoring-and-debugging/advanced-log-filtering#logging-postgres-queries).
|
||||
|
||||
|
||||
### Inspect a log
|
||||
|
||||
</TabPanel>
|
||||
<TabPanel id="storage" label="Storage">
|
||||
1. Select a row in the table.
|
||||
2. Open **Overview** to follow the request through the services that handled it. Open **Raw JSON** for the full event.
|
||||
3. Dock the panel at the bottom or on the right.
|
||||
|
||||
[Storage logs](/dashboard/project/_/logs/storage-logs) shows all server logs for your [Storage API](../../guides/storage).
|
||||
Edge Function rows include console output from that invocation. In SQL, the HTTP request is `function_edge_logs` and console output is `function_logs`. Function log messages longer than 10,000 characters are truncated.
|
||||
|
||||
|
||||
### Expanding results [#expanding-results]
|
||||
|
||||
</TabPanel>
|
||||
<TabPanel id="realtime" label="Realtime">
|
||||
In the [Logs Explorer](/dashboard/project/_/logs/explorer), query results can be hard to read in the table. Double-click a row to expand it as JSON:
|
||||
|
||||
[Realtime logs](/dashboard/project/_/logs/realtime-logs) show all server logs for your [Realtime API usage](../../guides/realtime).
|
||||
|
||||
|
||||
<Admonition type="note">
|
||||
### Single-service collections [#single-service-collections]
|
||||
|
||||
Realtime connections are not logged by default. Turn on [Realtime connection logs per client](#logging-realtime-connections) with the `log_level` parameter.
|
||||
The Logs sidebar still lists collections for one service at a time, such as [API Gateway](/dashboard/project/_/logs/edge-logs) or [Postgres](/dashboard/project/_/logs/postgres-logs). Use a collection when you want a dedicated view.
|
||||
|
||||
</Admonition>
|
||||
|
||||
|
||||
|
||||
</TabPanel>
|
||||
<TabPanel id="functions" label="Edge Functions">
|
||||
|
||||
For each [Edge Function](/dashboard/project/_/functions), logs are available under the following tabs:
|
||||
|
||||
**Invocations**
|
||||
|
||||
The Invocations tab displays the edge logs of function calls.
|
||||
|
||||
|
||||
|
||||
**Logs**
|
||||
|
||||
The Logs tab displays logs emitted during function execution.
|
||||
|
||||
|
||||
|
||||
**Log Message Length**
|
||||
|
||||
Edge Function log messages have a max length of 10,000 characters. If you try to log a message longer than that it will be truncated.
|
||||
|
||||
</TabPanel>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Working with API logs
|
||||
|
||||
[API logs](/dashboard/project/_/logs/edge-logs) run through the Cloudflare edge servers and will have attached Cloudflare metadata under the `metadata.request.cf.*` fields.
|
||||
|
||||
### Allowed headers
|
||||
|
||||
A strict list of request and response headers are permitted in the API logs. Request and response headers will still be received by the server(s) and client(s), but will not be attached to the API logs generated.
|
||||
|
||||
Request headers:
|
||||
|
||||
- `accept`
|
||||
- `cf-connecting-ip`
|
||||
- `cf-ipcountry`
|
||||
- `host`
|
||||
- `user-agent`
|
||||
- `x-forwarded-proto`
|
||||
- `referer`
|
||||
- `content-length`
|
||||
- `x-real-ip`
|
||||
- `x-client-info`
|
||||
- `x-forwarded-user-agent`
|
||||
- `range`
|
||||
- `prefer`
|
||||
|
||||
Response headers:
|
||||
|
||||
- `cf-cache-status`
|
||||
- `cf-ray`
|
||||
- `content-location`
|
||||
- `content-range`
|
||||
- `content-type`
|
||||
- `content-length`
|
||||
- `date`
|
||||
- `transfer-encoding`
|
||||
- `x-kong-proxy-latency`
|
||||
- `x-kong-upstream-latency`
|
||||
- `sb-gateway-mode`
|
||||
- `sb-gateway-version`
|
||||
|
||||
### Additional request metadata
|
||||
|
||||
To attach additional metadata to a request, it is recommended to use the `User-Agent` header for purposes such as device or version identification.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
node MyApp/1.2.3 (device-id:abc123)
|
||||
Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 MyApp/1.2.3 (Foo v1.3.2; Bar v2.2.2)
|
||||
```
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
Do not log Personal Identifiable Information (PII) within the `User-Agent` header, to avoid infringing data protection privacy laws. Overly fine-grained and detailed user agents may allow fingerprinting and identification of the end user through PII.
|
||||
|
||||
</Admonition>
|
||||
|
||||
## Logging Postgres connections
|
||||
|
||||
Postgres can log connection lifecycle events to your project's Postgres logs, for example when a client connects or authenticates. By default, Supabase sets `log_connections` to off for new projects and you must enable it first.
|
||||
|
||||
To enable connection logging for audit or compliance, see [Postgres connection logging](/docs/guides/platform/postgres-connection-logging).
|
||||
|
||||
In the [Logs Explorer](/dashboard/project/_/logs-explorer), connection lifecycle messages may be hidden by default. Use the connection logs filter in the sidebar to show them.
|
||||
|
||||
## Logging Postgres queries
|
||||
|
||||
To enable query logs for other categories of statements:
|
||||
|
||||
1. [Enable the pgAudit extension](/dashboard/project/_/database/extensions).
|
||||
2. Configure `pgaudit.log` (see below). Perform a fast reboot if needed.
|
||||
3. View your query logs under [Logs > Postgres Logs](/dashboard/project/_/logs/postgres-logs).
|
||||
|
||||
### Configuring `pgaudit.log`
|
||||
|
||||
The stored value under `pgaudit.log` determines the classes of statements that are logged by [pgAudit extension](https://www.pgaudit.org/). Refer to the pgAudit documentation for the [full list of values](https://github.com/pgaudit/pgaudit/blob/master/README.md#pgauditlog).
|
||||
|
||||
To enable logging for function calls/do blocks, writes, and DDL statements for a single session, execute the following within the session:
|
||||
|
||||
```sql
|
||||
-- temporary single-session config update
|
||||
set pgaudit.log = 'function, write, ddl';
|
||||
```
|
||||
|
||||
To _permanently_ set a logging configuration (beyond a single session), execute the following, then perform a fast reboot:
|
||||
|
||||
```sql
|
||||
-- equivalent permanent config update.
|
||||
alter role postgres set pgaudit.log to 'function, write, ddl';
|
||||
```
|
||||
|
||||
To help with debugging, we recommend adjusting the log scope to only relevant statements as having too wide of a scope would result in a lot of noise in your Postgres logs.
|
||||
|
||||
Note that in the above example, the role is set to `postgres`. To log user-traffic flowing through the [HTTP APIs](../../guides/database/api#rest-api-overview) powered by PostgREST, set your configuration values for the `authenticator`.
|
||||
|
||||
```sql
|
||||
-- for API-related logs
|
||||
alter role authenticator set pgaudit.log to 'write';
|
||||
```
|
||||
|
||||
By default, the log level will be set to `log`. To view other levels, run the following:
|
||||
|
||||
```sql
|
||||
-- adjust log level
|
||||
alter role postgres set pgaudit.log_level to 'info';
|
||||
alter role postgres set pgaudit.log_level to 'debug5';
|
||||
```
|
||||
|
||||
Note that as per the pgAudit [log_level documentation](https://github.com/pgaudit/pgaudit/blob/master/README.md#pgauditlog_level), `error`, `fatal`, and `panic` are not allowed.
|
||||
|
||||
To reset system-wide settings, execute the following, then perform a fast reboot:
|
||||
|
||||
```sql
|
||||
-- resets stored config.
|
||||
alter role postgres reset pgaudit.log
|
||||
```
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
If any permission errors are encountered when executing `alter role postgres ...`, it is likely that your project has yet to receive the patch to the latest version of [supautils](https://github.com/supabase/supautils), which is currently being rolled out.
|
||||
|
||||
</Admonition>
|
||||
|
||||
### `RAISE`d log messages in Postgres
|
||||
|
||||
Messages that are manually logged via `RAISE INFO`, `RAISE NOTICE`, `RAISE WARNING`, and `RAISE LOG` are shown in Postgres Logs. Note that only messages at or above your logging level are shown. Syncing of messages to Postgres Logs may take a few minutes.
|
||||
|
||||
If your logs aren't showing, check your logging level by running:
|
||||
|
||||
```sql
|
||||
show log_min_messages;
|
||||
```
|
||||
|
||||
Note that `LOG` is a higher level than `WARNING` and `ERROR`, so if your level is set to `LOG`, you will not see `WARNING` and `ERROR` messages.
|
||||
|
||||
### Limits and caveats
|
||||
|
||||
- Postgres log events on the Supabase Platform are limited to 100,000 characters. If a log event exceeds this limit, it will be truncated. This does not apply to self-hosting.
|
||||
- Internal connection logs to Postgres within the Supabase Platform by internal services are not logged. This does not apply to self-hosting.
|
||||
|
||||
## Logging realtime connections
|
||||
|
||||
Realtime doesn't log new WebSocket connections or Channel joins by default. Enable connection logging per client by including an `info` `log_level` parameter when instantiating the Supabase client.
|
||||
|
||||
```javascript
|
||||
import { createClient } from '@supabase/supabase-js'
|
||||
|
||||
const options = {
|
||||
realtime: {
|
||||
params: {
|
||||
log_level: 'info',
|
||||
},
|
||||
},
|
||||
}
|
||||
const supabase = createClient('https://xyzcompany.supabase.co', 'sb_publishable_...', options)
|
||||
```
|
||||
|
||||
## Logs Explorer
|
||||
|
||||
The [Logs Explorer](/dashboard/project/_/logs-explorer) exposes logs from each part of the Supabase stack as a separate table that can be queried and joined using SQL.
|
||||
|
||||
|
||||
|
||||
You can access the following logs from the **Sources** drop-down:
|
||||
|
||||
- `auth_logs`: GoTrue server logs, containing authentication/authorization activity.
|
||||
- `edge_logs`: Edge network logs, containing request and response metadata retrieved from Cloudflare.
|
||||
- `function_edge_logs`: Edge network logs for only edge functions, containing network requests and response metadata for each execution.
|
||||
- `function_logs`: Function internal logs, containing any `console` logging from within the edge function.
|
||||
- `postgres_logs`: Postgres database logs, containing statements executed by connected applications.
|
||||
- `realtime_logs`: Realtime server logs, containing client connection information.
|
||||
- `storage_logs`: Storage server logs, containing object upload and retrieval information.
|
||||
|
||||
## Querying with the Logs Explorer
|
||||
|
||||
The Logs Explorer runs on **ClickHouse**. Every log line from every source is a single row in the `logs` table, tagged by a `source` column. Structured fields live in a `log_attributes` map whose values are strings, and the raw line is in `event_message`.
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
ClickHouse has been the default engine since June 2026. Projects created before this date use BigQuery, whose `cross join unnest(metadata)` syntax is deprecated. We recommend rewriting those queries in the ClickHouse syntax shown in this guide.
|
||||
|
||||
</Admonition>
|
||||
|
||||
Read fields with bracket access, keeping the full dotted key, for example `log_attributes['request.path']` rather than `path`. Wrap numeric values in `toInt32OrZero(...)`, which returns `0` for a missing or non-numeric value. Use `count()` rather than `count(*)`.
|
||||
|
||||
For example, to find failing API requests:
|
||||
|
||||
```sql
|
||||
select timestamp,
|
||||
toInt32OrZero(log_attributes['response.status_code']) as status,
|
||||
log_attributes['request.path'] as path
|
||||
from logs
|
||||
where source = 'edge_logs'
|
||||
and toInt32OrZero(log_attributes['response.status_code']) >= 400
|
||||
order by timestamp desc
|
||||
limit 100;
|
||||
```
|
||||
|
||||
For example, to find a specific Postgres SQLSTATE (`42501` permission denied, `42P01` relation missing, `23505` duplicate key):
|
||||
|
||||
```sql
|
||||
select timestamp, log_attributes['parsed.user_name'] as role, event_message
|
||||
from logs
|
||||
where source = 'postgres_logs'
|
||||
and log_attributes['parsed.sql_state_code'] = '42501'
|
||||
order by timestamp desc
|
||||
limit 100;
|
||||
```
|
||||
|
||||
Do not guess `log_attributes` keys. A missing key returns an empty string rather than an error, so a wrong key makes a working query look empty instead of failing. Discover the real keys for a source, or read `event_message`, which always holds the full line. Statement text and error detail live there, not in `parsed.query` or `parsed.detail`, which are usually empty:
|
||||
|
||||
```sql
|
||||
select arrayJoin(mapKeys(log_attributes)) as key, count() as n
|
||||
from logs
|
||||
where source = 'postgres_logs'
|
||||
group by key
|
||||
order by n desc
|
||||
limit 100;
|
||||
```
|
||||
|
||||
If you use the [Supabase MCP server](/docs/guides/ai-tools/mcp), the `query_logs` tool runs a custom ClickHouse query like the ones above on hosted projects. The `get_logs` tool returns a service's recent logs without SQL; it is deprecated on hosted projects in favor of `query_logs`, and remains the option for local and self-hosted projects.
|
||||
|
||||
### LIMIT and result row limitations
|
||||
|
||||
The Logs Explorer has a maximum of 1000 rows per run. Use `LIMIT` to optimize your queries by reducing the number of rows returned further.
|
||||
|
||||
### Best practices
|
||||
|
||||
1. **Include a filter over the timestamp.**
|
||||
|
||||
Querying your entire log history might seem appealing. For **Enterprise** customers that have a large retention range, you run the risk of timeouts due additional time required to scan the larger dataset.
|
||||
|
||||
2. **Avoid selecting large nested objects; select individual values instead.**
|
||||
|
||||
When querying large objects, the columnar storage engine selects each column associated with each nested key, resulting in a large number of columns being selected. This inadvertently impacts the query speed and may result in timeouts or memory errors, especially for projects with a lot of logs.
|
||||
|
||||
Instead, select only the values required.
|
||||
|
||||
```sql
|
||||
-- ❌ Avoid this: selecting the whole attributes map
|
||||
select timestamp, log_attributes
|
||||
from logs
|
||||
where source = 'edge_logs';
|
||||
|
||||
-- ✅ Do this: select only the keys you need
|
||||
select timestamp, log_attributes['request.method'] as method
|
||||
from logs
|
||||
where source = 'edge_logs';
|
||||
```
|
||||
|
||||
3. **Query one source at a time.**
|
||||
|
||||
Identify which service owns the problem from the error or status code first, then query only that source. Scanning every source at once buries the signal you need and scans far more data than the investigation requires.
|
||||
|
||||
4. **Follow a request across sources with an anchor.** Once a query gives you an anchor such as a timestamp, request id, or SQL state, filter the adjacent source by that anchor to correlate the request across layers (for example `edge_logs` to `postgres_logs`), instead of re-scanning each source from scratch.
|
||||
|
||||
5. **Reference only fields you have confirmed.**
|
||||
|
||||
A misspelled or non-existent field name either errors or silently returns nothing, which leaves a working query look empty. Confirm field names in the [field reference](#logs-field-reference), or select `event_message` and inspect a sample row first.
|
||||
|
||||
### Logs field reference
|
||||
|
||||
Refer to the full field reference for each source below. Each source's structured fields are listed as ClickHouse `log_attributes` keys, alongside the base columns (`id`, `timestamp`, `event_message`, `severity_text`, `source`) that every source has.
|
||||
|
||||
<SharedData data="logConstants">
|
||||
{(logConstants) => {
|
||||
const otelBaseFields = [
|
||||
{ path: 'id', type: 'string' },
|
||||
{ path: 'timestamp', type: 'datetime' },
|
||||
{ path: 'event_message', type: 'string' },
|
||||
{ path: 'severity_text', type: 'string' },
|
||||
{ path: 'source', type: 'string' },
|
||||
]
|
||||
const baseColumns = new Set(otelBaseFields.map((field) => field.path))
|
||||
return (
|
||||
<Tabs
|
||||
scrollable
|
||||
size="small"
|
||||
type="underlined"
|
||||
defaultActiveId="edge_logs"
|
||||
queryGroup="source"
|
||||
>
|
||||
{logConstants.schemas.map((schema) => {
|
||||
const fields = [
|
||||
...otelBaseFields,
|
||||
...schema.fields
|
||||
.filter((field) => !baseColumns.has(field.path))
|
||||
.map((field) => ({
|
||||
path: `log_attributes['${field.path.replace(/^metadata\./, '')}']`,
|
||||
type: field.type,
|
||||
})),
|
||||
]
|
||||
return (
|
||||
<TabPanel id={schema.reference} key={schema.reference} label={schema.name}>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Path</th>
|
||||
<th>Type</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{fields.map((field) => (
|
||||
<tr>
|
||||
<td>{field.path}</td>
|
||||
<td>{field.type}</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</TabPanel>
|
||||
)
|
||||
})}
|
||||
</Tabs>
|
||||
)
|
||||
}}
|
||||
</SharedData>
|
||||
If [Read Replicas](/docs/guides/platform/read-replicas) are enabled, collections can filter by database with the **Source** control. For API logs from the [API Load Balancer](/docs/guides/platform/read-replicas#api-load-balancer), the upstream database is the Redirect Identifier field (`log_attributes['load_balancer_redirect_identifier']` in SQL).
|
||||
@@ -28,7 +28,7 @@ Connection logging supports audit and monitoring controls required by some compl
|
||||
- **HIPAA** — High-compliance projects should keep connection logging enabled. See the [shared responsibility model for healthcare data](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data) and [HIPAA compliance guide](/docs/guides/security/hipaa-compliance).
|
||||
- **SOC 2** — Users who need connection audit evidence should enable logging and retain logs according to their own policies. See the [SOC 2 compliance guide](/docs/guides/security/soc-2-compliance).
|
||||
|
||||
Disabling connection logging does not affect other Supabase logging (for example, [Platform Audit Logs](/docs/guides/security/platform-audit-logs), [Auth Audit Logs](/docs/guides/auth/audit-logs), or [pgAudit](/docs/guides/monitoring-and-debugging/logs#configuring-pgauditlog)).
|
||||
Disabling connection logging does not affect other Supabase logging (for example, [Platform Audit Logs](/docs/guides/security/platform-audit-logs), [Auth Audit Logs](/docs/guides/auth/audit-logs), or [pgAudit](/docs/guides/monitoring-and-debugging/advanced-log-filtering#configuring-pgauditlog)).
|
||||
|
||||
## Manage connection logging via the dashboard
|
||||
|
||||
@@ -38,7 +38,7 @@ Ensure that you have [Owner or Admin permissions](/docs/guides/platform/access-c
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
Connection events appear in Postgres logs. In the [Logs Explorer](/dashboard/project/_/logs-explorer), connection lifecycle messages may be hidden by default to reduce noise. Use the connection logs filter in the sidebar to show or hide them.
|
||||
Connection events appear in [Postgres logs](/docs/guides/monitoring-and-debugging/logs#postgres). They are included by default when the Postgres log type is selected. Clear **Connection logs** under Postgres to hide them.
|
||||
|
||||
</Admonition>
|
||||
|
||||
|
||||
@@ -152,7 +152,7 @@ When a Read Replica is deployed, it emits logs from the following services:
|
||||
- [PostgREST](/dashboard/project/_/logs/postgrest-logs)
|
||||
- [Supavisor](/dashboard/project/_/logs/pooler-logs)
|
||||
|
||||
Views on [Log Explorer](/docs/guides/monitoring-and-debugging/logs) are automatically filtered by databases, with the logs of the Primary database displayed by default. Viewing logs from other databases can be toggled with the `Source` button found on the upper-right part section of the Logs Explorer page.
|
||||
Single-service [log collections](/docs/guides/monitoring-and-debugging/logs#single-service-collections) filter by database, with the Primary database displayed by default. Switch databases with the **Source** control.
|
||||
|
||||
For API logs, logs can originate from the API Load Balancer as well. The upstream database or the one that eventually handles the request can be found under the `Redirect Identifier` field. This is equivalent to `metadata.load_balancer_redirect_identifier` when querying the underlying logs.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 'Learn how Supabase Storage caches objects with a CDN.'
|
||||
sidebar_label: 'CDN'
|
||||
---
|
||||
|
||||
Cache hits can be determined via the `log_attributes['response.headers.cf_cache_status']` key in the [logs](/docs/guides/monitoring-and-debugging/logs). Any value that corresponds to either `HIT`, `STALE`, `REVALIDATED`, or `UPDATING` is categorized as a cache hit.
|
||||
Cache hits can be determined via the `log_attributes['response.headers.cf_cache_status']` key in [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering#logs-explorer). Any value that corresponds to either `HIT`, `STALE`, `REVALIDATED`, or `UPDATING` is categorized as a cache hit.
|
||||
The following example query will show the top cache misses from the `edge_logs`:
|
||||
|
||||
```sql
|
||||
|
||||
@@ -11,7 +11,7 @@ For more advanced filtering needs, use the [SQL Editor](/dashboard/project/_/sql
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
For more details on filtering the log tables, see [Advanced Log Filtering](/docs/guides/monitoring-and-debugging/advanced-log-filtering)
|
||||
For more details on filtering the log tables, see [Query and filter logs](/docs/guides/monitoring-and-debugging/advanced-log-filtering)
|
||||
|
||||
</Admonition>
|
||||
|
||||
|
||||
+6
-27
@@ -39,7 +39,7 @@ limit 100;
|
||||
|
||||
The most useful fields for debugging are:
|
||||
|
||||
> NOTE: not every field is included below. For a full list, check the API Edge [field reference](/docs/guides/monitoring-and-debugging/logs#logs-field-reference)
|
||||
> NOTE: not every field is included below. For a full list, check the API Gateway and Function Edge [logs field reference](/docs/guides/monitoring-and-debugging/log-field-reference).
|
||||
|
||||
### Request object
|
||||
|
||||
@@ -98,21 +98,18 @@ limit 100;
|
||||
**Suggested use cases:**
|
||||
|
||||
- identify problematic queries
|
||||
- identify unusual behavior by authenticated users
|
||||
|
||||
| Column | Description | Sample value |
|
||||
| -------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| request.method | Request Method (PATCH, GET, PUT...) | GET |
|
||||
| request.url | Request URL, which contains the PostgREST formatted query | https://yuhplfrsdxxxtldakizi.supabase.co/rest/v1/users?select=username&id=eq.63b6190e-214f-4b8a-b72d-3af6e1921411&limit=1 |
|
||||
| request.sb.jwt.authorization.payload.subject | authenticated user's ID | 63b6190e-214f-4b8a-b72d-3af6e1921411 |
|
||||
| Column | Description | Sample value |
|
||||
| -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| request.method | Request Method (PATCH, GET, PUT...) | GET |
|
||||
| request.url | Request URL, which contains the PostgREST formatted query | https://yuhplfrsdxxxtldakizi.supabase.co/rest/v1/users?select=username&id=eq.63b6190e-214f-4b8a-b72d-3af6e1921411&limit=1 |
|
||||
|
||||
**Unnesting example:**
|
||||
|
||||
```sql
|
||||
select
|
||||
log_attributes['request.method'] as method,
|
||||
log_attributes['request.url'] as url,
|
||||
log_attributes['request.sb.jwt.authorization.payload.subject'] as auth_user
|
||||
log_attributes['request.url'] as url
|
||||
from logs
|
||||
where source = 'edge_logs'
|
||||
limit 100;
|
||||
@@ -291,21 +288,3 @@ group by ip
|
||||
order by ip_count desc
|
||||
limit 100;
|
||||
```
|
||||
|
||||
**Search frequented query paths by authenticated user:**
|
||||
|
||||
```sql
|
||||
select
|
||||
-- only available for front-end clients
|
||||
log_attributes['request.sb.jwt.authorization.payload.subject'] as auth_user,
|
||||
log_attributes['request.path'] as path,
|
||||
count() as request_count
|
||||
from logs
|
||||
where
|
||||
source = 'edge_logs'
|
||||
-- only look at DB API
|
||||
and match(log_attributes['request.path'], '^/rest/v1/')
|
||||
group by auth_user, path
|
||||
order by request_count desc
|
||||
limit 100;
|
||||
```
|
||||
@@ -13,14 +13,14 @@ export const telemetryDebugging: ContentListingGroup = {
|
||||
'Isolate the failing layer, read logs as evidence, and match symptoms to troubleshooting guides.',
|
||||
},
|
||||
{
|
||||
title: 'Logging',
|
||||
title: 'Logs',
|
||||
href: '/guides/monitoring-and-debugging/logs',
|
||||
description: 'Query events from any Supabase service using the Logs Explorer.',
|
||||
description: 'Inspect project log events in the unified Logs view in Studio.',
|
||||
},
|
||||
{
|
||||
title: 'Advanced log filtering',
|
||||
title: 'Query and filter logs',
|
||||
href: '/guides/monitoring-and-debugging/advanced-log-filtering',
|
||||
description: 'Regex filtering, structured-field queries, and field discovery in ClickHouse.',
|
||||
description: 'Run ClickHouse SQL from Studio, MCP, the API, or a script.',
|
||||
},
|
||||
{
|
||||
title: 'Troubleshooting index',
|
||||
|
||||
Reference in new issue
Block a user