Docs

Apps con Supabase

Vigila una app construida sobre Supabase, desde las llamadas del navegador a tu base de datos hasta las Edge Functions, con las llamadas a la base de datos como spans y las personas identificadas desde Supabase Auth.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. En el navegador
  2. Cómo se ve una llamada a la base de datos en Sypnia
  3. Identifica personas desde Supabase Auth
  4. En las Edge Functions
  5. Lo que esto no cubre
  6. Comprueba que funciona
  7. Las llamadas a la base de datos se registran
  8. Tus propias llamadas siguen funcionando
  9. La traza está unida

Esta guía es para una app cuyo backend es Supabase: el navegador habla con Supabase directamente, y quizá con unas pocas Edge Functions. Funciona con Sypnia Cloud y con un motor con alojamiento propio; agrega endpoint a cada init para tu propio motor.

Al final tendrás: cada llamada de la página a tu proyecto de Supabase registrada con su tabla y su estado, las llamadas fallidas (una regla de seguridad por filas que dice que no, una columna que falta) convertidas en problemas, las personas identificadas desde Supabase Auth, y tus Edge Functions trazadas con sus propias llamadas a la base de datos.

Necesitas: el SDK del navegador instalado, y la URL de tu proyecto de Supabase, como https://abcdefghijkl.supabase.co.

En el navegador

Por defecto el SDK registra solo las llamadas a tu propio origen. Tu proyecto de Supabase es otro origen, así que nómbralo.

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/`],
});
OpciónCubre¿Agrega encabezados?
recordTargetsTodo lo que llama supabase-js: la base de datos (/rest/v1/…), Auth (/auth/v1/…), Storage (/storage/v1/…).No. Los servicios propios de Supabase rechazarían encabezados que no conocen, y tus llamadas fallarían.
traceTargetsTus Edge Functions (/functions/v1/…).Sí: traceparent y x-sypnia-session, para que la función se una a la traza. Los permites en la función, más abajo.

No cambias nada en cómo creas o usas el cliente de Supabase.

Cómo se ve una llamada a la base de datos en Sypnia

Un supabase.from('orders').insert(order) rechazado por una regla de seguridad por filas se convierte en este evento:

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\""
}
  • La tabla está en la ruta, así que Rendimiento lista POST /rest/v1/orders con su velocidad y sus fallos, y un problema puede decir qué tabla rechazó.
  • El filtro nunca se envía. Supabase pone los filtros en la cadena de consulta (?email=eq.ada@example.com), y el SDK nunca registra una cadena de consulta.
  • Solo el código y el mensaje se leen de una respuesta fallida. Los campos details y hint, que pueden repetir la fila que falló, nunca se leen. Los datos de las filas y los cuerpos de las peticiones nunca se envían.
  • Las conexiones de Realtime no se registran: no son peticiones.

Qué respuestas cuentan como fallos: sin respuesta, 400, y 500 o más. Un 401 o un 404 es una respuesta. Una inserción que la seguridad por filas rechaza se registra con su 403, su código y su mensaje, y se cuenta en Rendimiento entre las respuestas 4xx de esa ruta; se vuelve un problema cuando tu código lanza un error por ella, que es lo que hace la mayoría del código.

Identifica personas desde 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);
});

El id es el id de usuario de Supabase, un UUID. Agrega email: session.user.email solo si quieres correos en Sypnia; mira Identificar personas. onAuthStateChange también se dispara cuando la página carga con un usuario con sesión iniciada, así que este único lugar alcanza.

En las Edge Functions

Las Edge Functions son funciones que reciben un Request y devuelven un Response, que es lo que traza wrapFetchHandler del SDK de Node. Impórtalo con el prefijo npm:.

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

Dos líneas son toda la integración: init, y wrapFetchHandler alrededor de tu manejador. Lo tercero que hay que hacer bien es el encabezado CORS: agrega traceparent y x-sypnia-session a Access-Control-Allow-Headers. Sin ellos el navegador se niega a llamar a la función una vez que figura en traceTargets.

Lo que obtienes por una llamada a esta función:

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
  • Las llamadas a la base de datos son spans. El SDK reconoce la dirección de la base de datos de Supabase y nombra el span por operación y tabla: SELECT carts, INSERT orders, UPDATE carts, DELETE cart_items, CALL create_order para una función de la base de datos llamada con rpc().
  • Las demás llamadas también son spans, con el nombre del método y la ruta.
  • Los errores que lanza el manejador se reportan con su pila, y la petición queda marcada como fallida.
  • La persona sale de la sesión del navegador que hizo la llamada. No identificas de nuevo.

El envío ocurre después de la respuesta, usando la forma que da la plataforma para mantener viva una función mientras trabaja en segundo plano, cuando la ofrece, y si no, esperando máximo 50 ms. Cómo corre Supabase el trabajo en segundo plano en las Edge Functions es función propia de Supabase: revisa su documentación actual si ves que faltan eventos de funciones cortas, y llama a await flush() antes de devolver como respaldo.

Lo que esto no cubre

No se cubrePor quéLa respuesta de hoy
Lo que pasa dentro de Postgres: triggers, funciones de la base de datos, consultas lentas por su planSypnia ve las llamadas a la base de datos, no su interior.Los reportes de base de datos del propio Supabase.
Webhooks de la base de datos y funciones programadas que ningún navegador llamóCorren, y se trazan si son Edge Functions con el envoltorio, como trazas propias sin sesión.—
Llamadas que los servicios de Supabase se hacen entre síNo son llamadas de tu app.—
Una app móvil nativa que usa SupabaseLos SDK nativos están Planeado.Una app de vista web funciona con el SDK del navegador.

Comprueba que funciona

  1. Las llamadas a la base de datos se registran

    Abre tu app con debug: true en init y haz algo que lea o escriba datos.

    Deberías ver
    La consola imprime eventos request con host igual a tu host de Supabase y path que empieza por /rest/v1/.
  2. Tus propias llamadas siguen funcionando

    Llama a una Edge Function desde la página.

    Deberías ver
    Responde como antes. Si la consola del navegador muestra un error de CORS que nombra traceparent, al Access-Control-Allow-Headers de la función le faltan los dos encabezados.
  3. La traza está unida

    En menos de 10 minutos, abre en Sypnia la traza de esa llamada.

    Deberías ver
    Una sola traza: la llamada del navegador, la petición de la función debajo, y las llamadas de la función a la base de datos debajo de esa.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar