Docs

Supabase apps

Watch an app built on Supabase, from the browser's calls to your database through to Edge Functions, with database calls as spans and people identified from Supabase Auth.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. In the browser
  2. What a database call looks like in Sypnia
  3. Identify people from Supabase Auth
  4. In Edge Functions
  5. What this does not cover
  6. Check that it works
  7. The database calls are recorded
  8. Your own calls still work
  9. The trace is joined

This guide is for an app whose backend is Supabase: the browser talks to Supabase directly, and maybe to a few Edge Functions. It works with Sypnia Cloud and with a self-hosted engine; add endpoint to each init for your own engine.

At the end you will have: every call from the page to your Supabase project recorded with its table and its status, failed calls (a row-level security rule that says no, a missing column) turned into problems, people identified from Supabase Auth, and your Edge Functions traced with their own database calls.

You need: the browser SDK installed, and your Supabase project’s URL, such as https://abcdefghijkl.supabase.co.

In the browser

By default the SDK records calls to your own origin only. Your Supabase project is another origin, so name it.

src/main.ts
import { init } from '@sypnia/browser';

const SUPABASE_URL = 'https://abcdefghijkl.supabase.co';

init({
  project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
  environment: location.hostname === 'shop.example' ? 'production' : 'development',
  recordTargets: [SUPABASE_URL],
  traceTargets: [`${SUPABASE_URL}/functions/v1/`],
});
OptionCoversAdds headers?
recordTargetsEverything supabase-js calls: the database (/rest/v1/…), Auth (/auth/v1/…), Storage (/storage/v1/…).No. Supabase’s own services would refuse headers they do not know, and your calls would fail.
traceTargetsYour Edge Functions (/functions/v1/…).Yes: traceparent and x-sypnia-session, so the function joins the trace. You allow them in the function, below.

You change nothing in how you create or use the Supabase client.

What a database call looks like in Sypnia

supabase.from('orders').insert(order) refused by a row-level security rule becomes this event:

JSON
{
  "type": "request",
  "method": "POST",
  "host": "abcdefghijkl.supabase.co",
  "path": "/rest/v1/orders",
  "status": 403,
  "dur": 87,
  "code": "42501",
  "msg": "new row violates row-level security policy for table \"orders\""
}
  • The table is in the path, so Performance lists POST /rest/v1/orders with its speed and its failures, and a problem can say which table refused.
  • The filter is never sent. Supabase puts filters in the query string (?email=eq.ada@example.com), and the SDK never records a query string.
  • Only the code and the message are read from a failed answer. The details and hint fields, which can repeat the row that failed, are never read. Row data and request bodies are never sent.
  • Realtime connections are not recorded: they are not requests.

Which answers count as failures: no answer, 400, and 500 or above. A 401 or a 404 is an answer. An insert that row-level security refuses is recorded with its 403, its code and its message, and is counted in Performance among that route’s 4xx answers; it becomes a problem when your code throws because of it, which most code does.

Identify people from Supabase Auth

src/auth.ts
import { identify } from '@sypnia/browser';
import { supabase } from './supabase';

supabase.auth.onAuthStateChange((_event, session) => {
  if (session) identify({ person: { id: session.user.id } });
  else identify(null);
});

The id is Supabase’s user id, a UUID. Add email: session.user.email only if you want e-mail addresses in Sypnia; see Identifying people. onAuthStateChange also fires when the page loads with a signed-in user, so this one place is enough.

In Edge Functions

Edge Functions are functions from a Request to a Response, which is what wrapFetchHandler of the Node SDK traces. Import it with the npm: prefix.

supabase/functions/checkout/index.ts
import { createClient } from 'npm:@supabase/supabase-js@2';
import { init, wrapFetchHandler } from 'npm:@sypnia/node';

init({
  project: Deno.env.get('SYPNIA_PROJECT_KEY'),
  service: 'checkout-function',
  environment: Deno.env.get('SYPNIA_ENVIRONMENT') ?? 'production',
});

const cors = {
  'Access-Control-Allow-Origin': 'https://shop.example',
  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type, traceparent, x-sypnia-session',
};

Deno.serve(wrapFetchHandler(async (request: Request) => {
  if (request.method === 'OPTIONS') return new Response('ok', { headers: cors });

  const supabase = createClient(Deno.env.get('SUPABASE_URL')!, Deno.env.get('SUPABASE_ANON_KEY')!, {
    global: { headers: { Authorization: request.headers.get('Authorization')! } },
  });

  const { data: cart, error } = await supabase.from('carts').select('id, total_cents').single();
  if (error) throw error;

  const payment = await fetch('https://payments.example/v1/payments', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ amount: cart.total_cents }),
  });

  return Response.json({ ok: payment.ok }, { status: payment.ok ? 200 : 502, headers: cors });
}));
Terminal
supabase secrets set SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
supabase functions deploy checkout

Two lines are the whole integration: init, and wrapFetchHandler around your handler. The third thing to get right is the CORS header: add traceparent and x-sypnia-session to Access-Control-Allow-Headers. Without them the browser refuses to call the function once it is listed in traceTargets.

What you get for one call to this function:

Text
click «Pay $64.00»                                        browser
└─ POST /functions/v1/checkout              412 ms  502   checkout-function
   ├─ SELECT carts                           18 ms  ok    database
   └─ POST /v1/payments                     340 ms  400   payments.example   <- failed
  • Database calls are spans. The SDK recognizes Supabase’s database address and names the span by operation and table: SELECT carts, INSERT orders, UPDATE carts, DELETE cart_items, CALL create_order for a database function called with rpc().
  • Other calls are spans too, named by method and path.
  • Errors thrown by the handler are reported with their stack, and the request is marked failed.
  • The person comes from the browser session that made the call. You do not identify again.

Sending happens after the response, using the platform’s way to keep a function alive for background work when it offers one, and otherwise waiting at most 50 ms. How Supabase runs background work in Edge Functions is its own feature: check Supabase’s current documentation if you see events missing from short functions, and call await flush() before returning as a fallback.

What this does not cover

Not coveredWhyToday’s answer
What happens inside Postgres: triggers, database functions, slow queries by planSypnia sees calls to the database, not the database’s inside.Supabase’s own database reports.
Database webhooks and scheduled functions that no browser calledThey run, and are traced if they are Edge Functions with the wrapper, as traces of their own without a session.—
Calls made by Supabase’s services to each otherThey are not your app’s calls.—
A native mobile app using SupabaseNative SDKs are Planned.A web-view app works with the browser SDK.

Check that it works

  1. The database calls are recorded

    Open your app with debug: true in init and do something that reads or writes data.

    You should see
    The console prints request events with host set to your Supabase host and path starting with /rest/v1/.
  2. Your own calls still work

    Call an Edge Function from the page.

    You should see
    It answers as before. If the browser’s console shows a CORS error that names traceparent, the function’s Access-Control-Allow-Headers is missing the two headers.
  3. The trace is joined

    Within 10 minutes, open the trace of that call in Sypnia.

    You should see
    One trace: the browser’s call, the function’s request under it, and the function’s database calls under that.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close