Query and filter logs

This guide explains how to query project logs and how to record extra events. The same ClickHouse SQL runs in the Logs Explorer, the MCP query_logs tool, and the Management API. Filter events without SQL in Logs in Studio. From a terminal, call the Management API; the CLI inspects the database rather than ClickHouse logs.

Use this page to:

• Query logs from Studio, MCP, the API, or a script
• Pick a source for the layer that reported the error
• Record extra API, Postgres, and Realtime events
• Write ClickHouse SQL

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.

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 #

Open Logs to filter and inspect events. Open the Logs Explorer to run ClickHouse SQL. See Logs for the unified Logs interface.

MCP #

On hosted projects, call query_logs with the same SQL as this guide. Keep the connection project-scoped and read-only.

API #

Pass ClickHouse SQL in the sql parameter of the Management API logs endpoint. 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 #

The Supabase CLI does not query ClickHouse logs. Call the Management API from a script, or use supabase inspect db for database diagnostics.

Sources #

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.

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.

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 for the ClickHouse field names on each source.

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:

1
node MyApp/1.2.3 (device-id:abc123)
2
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)

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.

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 #

To enable query logs for other categories of statements:

1. Enable the pgAudit extension.
2. Configure pgaudit.log (see below). Perform a fast reboot if needed.
3. View your query logs in Logs. Filter Log Type to Postgres.

Configuring pgaudit.log#

The stored value under pgaudit.log determines the classes of statements that are logged by pgAudit extension. Refer to the pgAudit documentation for the full list of values.

To enable logging for function calls/do blocks, writes, and DDL statements for a single session, execute the following within the session:

1
-- temporary single-session config update
2
set pgaudit.log = 'function, write, ddl';

To permanently set a logging configuration (beyond a single session), execute the following, then perform a fast reboot:

1
-- equivalent permanent config update.
2
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, which use PostgREST, set your configuration values for the authenticator.

1
-- for API-related logs
2
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:

1
-- adjust log level
2
alter role postgres set pgaudit.log_level to 'info';
3
alter role postgres set pgaudit.log_level to 'debug5';

Note that as per the pgAudit log_level documentation, error, fatal, and panic are not allowed.

To reset system-wide settings, execute the following, then perform a fast reboot:

1
-- resets stored config.
2
alter role postgres reset pgaudit.log

RAISEd 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:

1
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.

1
import { createClient } from '@supabase/supabase-js'
2
3
const options = {
4
  realtime: {
5
    params: {
6
      log_level: 'info',
7
    },
8
  },
9
}
10
const supabase = createClient('https://xyzcompany.supabase.co', 'sb_publishable_...', options)

Querying logs #

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:

1
select timestamp,
2
       toInt32OrZero(log_attributes['response.status_code']) as status,
3
       log_attributes['request.path'] as path
4
from logs
5
where source = 'edge_logs'
6
  and toInt32OrZero(log_attributes['response.status_code']) >= 400
7
order by timestamp desc
8
limit 100;

For example, to find a specific Postgres SQLSTATE (42501 permission denied, 42P01 relation missing, 23505 duplicate key):

1
select timestamp, log_attributes['parsed.user_name'] as role, event_message
2
from logs
3
where source = 'postgres_logs'
4
  and log_attributes['parsed.sql_state_code'] = '42501'
5
order by timestamp desc
6
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. MCP and the Management API require an explicit time range.

1
select timestamp, event_message
2
from logs
3
where source = 'edge_logs'
4
order by timestamp desc
5
limit 100;

Reading fields from log_attributes#

Structured fields live in the log_attributes map. Read a field with bracket access, keeping the full dotted key. There are no unnesting joins.

1
select
2
  log_attributes['request.method'] as method,
3
  log_attributes['request.path'] as path,
4
  log_attributes['response.status_code'] as status
5
from logs
6
where source = 'edge_logs'
7
limit 100;

The key keeps the full dotted path, with the metadata root dropped. What BigQuery expressed as metadata.request.cf.country is log_attributes['request.cf.country']. Keep the full prefix rather than shortening it.

Map values are always strings. To compare or aggregate a numeric field, wrap it in toInt32OrZero, which returns 0 for a missing or non-numeric value:

1
select count() as server_errors
2
from logs
3
where source = 'edge_logs'
4
  and toInt32OrZero(log_attributes['response.status_code']) between 500 and 599;

Do not guess keys. Discover the keys a source sets from recent rows:

1
select arrayJoin(mapKeys(log_attributes)) as key, count() as n
2
from logs
3
where source = 'postgres_logs'
4
group by key
5
order by n desc
6
limit 100;

LIMIT and result row limitations#

The Logs Explorer has a maximum of 1000 rows per run. Use LIMIT to reduce the number of rows returned further.

Best practices#

1. Use a narrow time range.

The Logs Explorer applies the time range you select, so keep it tight. Querying a very large range risks timeouts, especially for Enterprise customers with long retention, because of the extra data scanned.

2. Select only the fields you need.

Selecting the whole log_attributes map, or every column, reads far more data than you need and slows the query down. Select the specific keys instead.

1
-- ❌ Avoid this: selecting the whole attributes map
2
select timestamp, log_attributes
3
from logs
4
where source = 'edge_logs';
5
6
-- ✅ Do this: select only the keys you need
7
select timestamp, log_attributes['request.method'] as method
8
from logs
9
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, 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.

For example, you can enter the following query in the SQL Editor to retrieve each user's IP address:

1
select timestamp, log_attributes['request.headers.x_real_ip'] as x_real_ip
2
from logs
3
where source = 'edge_logs'
4
  and log_attributes['request.headers.x_real_ip'] != ''
5
  and log_attributes['request.method'] = 'GET'
6
order by timestamp desc
7
limit 100;

Understanding field references#

Every log source shares the same logs table. Each row has these columns:

Service-specific details live in log_attributes. For example, in postgres_logs the log_attributes['parsed.error_severity'] field holds the error level of an event. Read those fields with bracket access:

1
select
2
  event_message,
3
  log_attributes['parsed.error_severity'] as error_severity,
4
  log_attributes['parsed.user_name'] as user_name
5
from logs
6
where source = 'postgres_logs'
7
limit 100;

Filtering with regular expressions#

Use the ClickHouse match function for regular expressions. In its most basic form, it checks whether a pattern is present in a column.

1
select timestamp, event_message
2
from logs
3
where source = 'postgres_logs'
4
  and match(event_message, 'is present')
5
limit 100;

There are multiple operators to consider using.

Find messages that start with a phrase#

^ only looks for values at the start of a string

1
-- find only messages that start with connection
2
match(event_message, '^connection')

Find messages that end with a phrase#

$ only looks for values at the end of the string

1
-- find only messages that end with port=12345
2
match(event_message, 'port=12345$')

Ignore case sensitivity#

(?i) ignores capitalization for all proceeding characters

1
-- find all event_messages with the word "connection"
2
match(event_message, '(?i)COnnecTion')

For a plain case-insensitive substring match, ilike is simpler:

1
-- find all event_messages containing "connection", in any case
2
event_message ilike '%connection%'

Wildcards#

. matches any single character, and .* matches any sequence of characters

1
-- find event_messages like "hello<anything>world"
2
match(event_message, 'hello.*world')

Alphanumeric ranges#

[0-9a-zA-Z] matches a single alphanumeric character. Anchor it with ^[0-9a-zA-Z]+$ to match a value that is entirely alphanumeric.

1
-- find event_messages that contain a digit between 1 and 5 (inclusive)
2
match(event_message, '[1-5]')

Repeated values#

x* zero or more x x+ one or more x x? zero or one x x{4,} four or more x x{3} exactly 3 x

1
-- find event_messages that contain any sequence of 3 digits
2
match(event_message, '[0-9]{3}')

Escaping reserved characters#

\. is interpreted as a period . instead of as a wildcard

1
-- escapes .
2
match(event_message, 'hello world\.')

or statements#

x|y any string with x or y present

1
-- find event_messages that have the word 'started' followed by either "host" or "authenticated"
2
match(event_message, 'started (host|authenticated)')

and/or/not statements in SQL#

and, or, and not are native terms in SQL and can be used with regular expressions to filter results

1
select timestamp, event_message
2
from logs
3
where source = 'postgres_logs'
4
  and (
5
    (match(event_message, 'connection') and match(event_message, 'host'))
6
    or not match(event_message, 'received')
7
  )
8
limit 100;

Filtering example#

Filter for Postgres errors:

1
select
2
  timestamp,
3
  log_attributes['parsed.error_severity'] as error_severity,
4
  log_attributes['parsed.user_name'] as user_name,
5
  event_message
6
from logs
7
where source = 'postgres_logs'
8
  and match(log_attributes['parsed.error_severity'], 'ERROR|FATAL|PANIC')
9
order by timestamp desc
10
limit 100;

Limitations#

The wildcard operator * is not supported#

The logs query surface rejects select * and count(*). List the columns you need, and use count() for row counts:

1
select timestamp, event_message, log_attributes['parsed.error_severity'] as error_severity
2
from logs
3
where source = 'postgres_logs'
4
order by timestamp desc
5
limit 100;