Field Guide: Set Up Supabase Observability with Unified Logs and Grafana Cloud in 25 Minutes

If your team already uses Supabase in production, the observability story changed over the last two weeks. On July 16, 2026, Supabase pushed Unified Logs into open beta. On July 23, 2026, it followed with one-click Grafana Cloud setup for metrics on every plan, including free. Put together, those two releases give you a much faster way to answer the two questions that matter during an incident: what just happened, and is the database getting healthier or worse?

This field guide is the shortest path to a usable setup.

What shipped, in plain English

Here is the practical split:

Unified Logs is for event-level debugging. You use it to inspect auth failures, API requests, storage activity, edge function logs, or Postgres log lines.
Grafana Cloud is for metrics. You use it to watch CPU, IO, replication lag, connection pressure, checkpoints, and query behavior over time.

That distinction matters because Supabase’s July 23 launch is metrics-first. The official launch post says the one-click integration sets up authentication, metric scraping, and a prebuilt dashboard with more than 200 metrics. It also says log drains to Grafana Cloud are still in progress, so do not assume your logs will automatically land in Grafana.

The 25-minute setup order

Use this order and you avoid the usual dashboard-first confusion.

Open Supabase Dashboard -> Integrations and connect Grafana Cloud.
Confirm the project is attached to a Grafana Cloud stack with Prometheus enabled.
Let the one-click path create the scrape job automatically if it is offered in your dashboard.
Open the installed dashboards and check that the Supabase Project view is receiving fresh data.
In parallel, open Logs Explorer in Supabase and save one or two high-signal queries for common failures.

The docs are clear about the recommended path: use the Dashboard integration first, and only drop to manual setup if you need custom topology or a non-standard Prometheus route.

The metrics checklist that is worth checking on day one

Supabase says the built-in dashboard groups metrics around the signals that matter when debugging a production issue. For a first pass, ignore the long tail and look at these first:

CPU and memory pressure
Disk IO and throughput
Connection counts and pooler behavior
Replication lag
Database size and query stats

Grafana’s own integration docs also confirm you should see two installed dashboards: Metrics endpoint scrape overview and Supabase Project. If you only see a scrape dashboard and not the project dashboard, the install is incomplete even if credentials tested successfully.

The logs queries to save before you need them

Supabase’s logs docs matter here because Unified Logs is not just a prettier filter bar. The platform now exposes one logs table, tagged by source, and the query engine is ClickHouse by default for projects created since June 2026.

Start with one simple query per failure mode. For HTTP and auth noise, keep the query tight and recent:

sql

select
  timestamp,
  source,
  event_message,
  log_attributes['response.status_code'] as status
from logs
where source in ('edge_logs', 'auth_logs')
  and timestamp >= now() - interval 15 minute
order by timestamp desc
limit 100

For database debugging, switch to postgres_logs and narrow the time range aggressively. Supabase warns that the Logs Explorer caps each run at 1000 rows, so broad scans waste time and quota.

The one small client change that makes Realtime debugging less blind

If your incident pattern includes dropped subscriptions or noisy channels, turn on Realtime connection logging in the client before the next outage. Supabase documents this directly:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(url, key, {
  realtime: {
    params: {
      log_level: 'info',
    },
  },
})

This gives you better correlation inside realtime_logs when users say “live updates stopped” and nobody can reproduce it locally.

The billing trap to avoid

The new observability workflow is better, but it is not free just because the UI looks integrated. Supabase’s current usage docs split logs into two separate meters:

Logs Ingest: how much log data Supabase processes
Logs Query: how much data you scan when reading logs

As of July 30, 2026, the published quotas say Pro and Team projects include 5 GB of Logs Ingest and 1,000 GB of Logs Query per month before overage pricing applies. That means sloppy query habits become a cost problem quickly.

The safe default is simple: always filter by time first, avoid selecting huge nested objects unless you need them, and save targeted queries instead of rerunning broad exploratory scans.

When to stay with one-click, and when to go manual

Stay with the one-click path when:

You want fast setup on a real project today
Your team already uses Grafana Cloud
You do not need custom scrape routing

Drop to manual setup when:

You need self-hosted Prometheus or Grafana
You want to reuse an existing Grafana Agent pipeline
You need tighter control over credentials, intervals, or routing

Supabase’s manual docs still use the same Metrics API endpoint and the same sb_secret_... credential shape. The difference is operational control, not a different data model.

The operating model that actually works

The cleanest setup is not “put everything in Grafana.” It is:

Use Grafana Cloud for ongoing health, trend lines, and alerts.
Use Unified Logs in Supabase for incident drills, request-level forensics, and recent-failure triage.
Add external log drains later only if you truly need cross-system retention or centralized alert routing.

That is the late-July takeaway. Supabase now gives you a fast native split between metrics and logs. If you adopt that split instead of forcing both tools to do the same job, you get to useful answers faster.