Docs

Node

Traza cada petición que atiende tu servidor Node y cada llamada que hace, únelas a la sesión del navegador que las causó y reporta los errores del servidor, con un solo import.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Instalar
  2. Comprueba que funciona
  3. Qué se traza sin escribir código
  4. Cuándo falló una llamada
  5. Peticiones que nunca terminan
  6. Unir el navegador con el servidor
  7. init(options)
  8. Errores
  9. Las funciones que llamas tú
  10. reportError(error)
  11. identify(who)
  12. span(name, fn, attrs?)
  13. flush(timeoutMs?) y shutdown(timeoutMs?)
  14. wrapFetchHandler(handler)
  15. Apagado ordenado
  16. Serverless y otros entornos
  17. Costo
  18. Sigue con

Esta página es para quien corre un servidor Node: una API, el backend de una app web, un sitio que pinta en el servidor. @sypnia/node tiene licencia MIT y es idéntico para el motor de código abierto y para Sypnia Cloud; solo cambian la dirección y de dónde sale la llave. Para Next.js usa @sypnia/next, que ya lo incluye.

Al final tendrás: cada petición entrante trazada sin poner ninguna llamada a mano, sus llamadas a la base de datos y a otros servicios como spans, los errores del servidor como problemas, y cada traza unida a la sesión del navegador que la empezó.

Instalar

npm

npm install @sypnia/node

Crea un archivo que arranque Sypnia, e impórtalo antes que cualquier otra cosa en el archivo de entrada de tu servidor.

Sypnia Cloud

src/instrument.ts
import { init } from '@sypnia/node';

init({
  project: process.env.SYPNIA_PROJECT_KEY,
  service: 'shop-api',
  environment: process.env.SYPNIA_ENVIRONMENT ?? 'production',
  release: process.env.SYPNIA_RELEASE,
});
src/server.ts
import './instrument';
import express from 'express';

const app = express();
app.post('/api/checkout', checkout);
app.listen(3000);
.env
SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
SYPNIA_ENVIRONMENT=production
SYPNIA_RELEASE=4f2a91c

Usa el mismo proyecto que tu frontend, y los mismos nombres de environment y release. Una traza une partes de un mismo proyecto en un mismo entorno.

Comprueba que funciona

  1. Arranca tu servidor con debug: true en init.
  2. Llama a cualquier ruta: curl -i http://localhost:3000/api/checkout -X POST.
  3. La consola imprime un evento server_request con el método, la ruta, el estado y sus spans, y luego sent 1 event (200).

Qué se traza sin escribir código

QuéCubreSe convierte en
Peticiones entrantesToda petición a un servidor construido sobre el módulo http o https de Node: Express, Fastify, Koa, NestJS, Hono en Node, http simple.Un server_request con método, ruta, estado y duración.
Llamadas HTTP salientesfetch, y http.request / https.request (o sea, también axios, got y la mayoría de SDK).Un span de clase http, con nombre POST /v1/payments.
Consultas a PostgresEl paquete pg.Un span de clase db, con el nombre de la operación y la tabla: SELECT carts. Nunca los valores de la sentencia.
Llamadas a Supabase y PostgRESTSe reconocen entre las llamadas salientes por su ruta (/rest/v1/…).Un span de clase db: SELECT orders, INSERT orders, CALL create_order.
ErroresLos de la sección Errores, más abajo.server_error

Otros controladores de bases de datos (MySQL, MongoDB, Redis, el motor propio de Prisma) están Planeado. Mientras tanto envuelve la llamada en span(), o usa su instrumentación de OpenTelemetry con la entrada OTLP.

No se traza por defecto: las peticiones OPTIONS, y las peticiones de archivos estáticos (una ruta que termina en .js, .css, .map, .png, .jpg, .jpeg, .gif, .svg, .ico, .webp, .avif, .woff, .woff2, .ttf, .txt, .xml o .webmanifest). Agrega tu chequeo de salud con ignoreRoutes.

Nunca se lee: cuerpos de peticiones y respuestas, cookies, encabezados distintos de traceparent y x-sypnia-session, ni cadenas de consulta. El nombre y los atributos de un span llevan el método, el host, la ruta y el estado, nada más.

Cuándo falló una llamada

Una llamada que hace tu servidor falló cuando no recibe respuesta, responde 400, o responde 500 o más. Una petición que recibe tu servidor falló cuando responde 500 o más, o lanza un error. Respuestas como 401, 404 y 409 son respuestas, no fallos.

Peticiones que nunca terminan

Una petición que sigue corriendo tras 20 segundos se reporta en ese momento como registro parcial: los spans que terminaron y las llamadas que siguen en curso. Si la petición termina, el registro completo lo reemplaza. Si la plataforma la mata, el registro parcial es lo que tienes. Cambia el umbral con slowRequestMs.

Unir el navegador con el servidor

El SDK del navegador agrega dos encabezados a las llamadas a tu API. El SDK de Node los lee, así que no haces nada:

EncabezadoSe lee como
traceparentEl id de traza y el span padre. Los spans del servidor se unen a la traza del navegador. Sin él, el servidor empieza una traza nueva.
x-sypnia-sessionEl id de sesión. La petición aparece en la línea de tiempo de esa sesión, y sus fallos cuentan para la persona de esa sesión.

En cada llamada saliente, el SDK agrega traceparent con la traza actual, para que el siguiente servicio la continúe: otro servidor Node con este SDK, o cualquier backend con un SDK de OpenTelemetry. Nunca reenvía x-sypnia-session, y nunca reemplaza un traceparent que tu código ya puso.

Si el navegador llama a tu API en otro origen, la API debe permitir ambos encabezados en CORS. Mira Navegador.

init(options)

OpciónTipoPor defectoQué hace
projectstringprocess.env.SYPNIA_PROJECT_KEYLa llave de ingesta, spk_…. Sin ella el SDK no hace nada e imprime un solo aviso.
endpointstringprocess.env.SYPNIA_ENDPOINT, si no 'https://ingest.sypnia.com'A dónde enviar. La URL base de un motor con alojamiento propio.
servicestring, hasta 80 caracteresprocess.env.SYPNIA_SERVICE, si no 'server'El nombre de este servicio en las trazas.
environmentstring, de 1 a 40 caracteresprocess.env.SYPNIA_ENVIRONMENT, si no 'production'El entorno. Usa los mismos nombres que el frontend.
releasestring, hasta 40 caracteresprocess.env.SYPNIA_RELEASE, si no ningunoLa versión (release). Usa el commit corto de git.
enabledbooleantruefalse deja el SDK sin efecto.
debugbooleanfalseImprime en la consola cada evento y cada envío.
ignoreRoutes(string | RegExp)[][]Rutas entrantes que no se trazan, además de las de arriba. Un texto cubre la ruta y todo lo que cuelga de ella.
routeFor(pathname: string) => stringla regla incluidaTu propia forma de convertir una ruta con ids en una ruta genérica. Por defecto el SDK usa el patrón de ruta de Express y Fastify cuando puede leerlo (/orders/:id), y si no, la misma regla que el navegador.
capture.outgoingbooleantrueSpans para las llamadas HTTP salientes.
capture.dbbooleantrueSpans para pg, y nombres para las llamadas a Supabase y PostgREST.
capture.consoleErrorsbooleantrueReporta como fallo un console.error durante una petición.
capture.uncaughtbooleantrueReporta excepciones sin capturar y rechazos sin manejar.
propagatebooleantrueAgrega traceparent a las llamadas salientes.
slowRequestMsnumber20000Cuándo se reporta como parcial una petición que sigue corriendo. 0 lo apaga.
flushBudgetMsnumber50Lo máximo que el SDK espera un envío al final de una invocación serverless.
beforeSend(event) => event | nullningunoSe llama con cada evento antes de encolarlo. Devuelve null para descartarlo.

Límites fijos: se conservan 200 spans por petición (el resto se cuenta), 64 atributos por span, 5 fallos por petición de los cuales 3 de console.error, uno por huella. Están en el esquema de eventos.

Errores

Se captura sin códigoCómo aparece
Una excepción que nadie capturó, o un rechazo sin manejarUn fallo con su pila. El SDK lo reporta y no cambia lo que Node hace después.
Una llamada que falló (mira arriba)Un fallo con el nombre de la llamada, como HTTP 400 o DB 23505. Su mensaje se depura antes de salir de tu servidor: correos, URL, UUID, valores entre comillas, tokens largos y toda serie de dígitos se reemplazan.
Una petición respondida con 500 o más, sin otro falloUn fallo llamado HTTP 500, con la ruta.
console.error mientras se atiende una peticiónUn fallo con el texto registrado, y la pila si se registró un Error.

Los frameworks capturan los errores lanzados en tus manejadores y los convierten en un 500. Sypnia sabe entonces que la petición falló, pero no por qué. Entrega el error con una línea, para que el problema tenga su pila:

Express

src/server.ts
import { reportError } from '@sypnia/node';

// después de todas las rutas
app.use((error, req, res, next) => {
  reportError(error);
  next(error);
});

Las funciones que llamas tú

reportError(error)

Reporta un error que tu código capturó. Dentro de una petición queda unido a la traza y a la sesión de esa petición.

identify(who)

Dice a quién pertenece una petición. Solo la necesitas para peticiones que no vienen de una sesión de navegador identificada: una app móvil, un cliente de la API, un webhook. En las demás, Sypnia ya conoce a la persona por la sesión.

src/auth-middleware.ts
import { identify } from '@sypnia/node';

app.use((req, res, next) => {
  if (req.user) identify({ person: { id: req.user.id }, account: { id: req.user.accountId } });
  next();
});

Aplica solo a la petición actual. Mira Identificar personas.

span(name, fn, attrs?)

Registra un paso tuyo como span de clase internal, alrededor de una función. Devuelve lo que devuelve la función, y marca el span como fallido si la función lanza un error.

src/checkout.ts
import { span } from '@sypnia/node';

const total = await span('price cart', () => priceCart(cart), { 'cart.items': cart.items.length });

name tiene máximo 120 caracteres. Los valores de attrs son textos de máximo 256 caracteres, números o booleanos.

flush(timeoutMs?) y shutdown(timeoutMs?)

flush envía lo que está esperando y termina cuando se envió o tras timeoutMs (2.000 por defecto). shutdown hace lo mismo y luego detiene el SDK.

wrapFetchHandler(handler)

Para entornos donde un servidor es una función que recibe un Request y devuelve un Response. Mira la sección Serverless, más abajo.

Los eventos propios (track) se envían solo desde el navegador al lanzar.

Apagado ordenado

Los eventos esperan en memoria hasta 2 segundos antes de enviarse en un lote. Cuando a tu proceso le piden detenerse, envíalos primero:

src/server.ts
import { shutdown } from '@sypnia/node';

process.on('SIGTERM', async () => {
  server.close();
  await shutdown(2000);
  process.exit(0);
});

El SDK envía solo cuando el bucle de eventos se vacía (beforeExit). No instala manejadores de señales: eso cambiaría cómo se detiene tu proceso.

Serverless y otros entornos

Dónde correQué hacerEstado
Un servidor Node de larga vida, Node 20 o más nuevoimport './instrument' primero. Todo lo de esta página.Al lanzar
Next.js@sypnia/next.Al lanzar
Funciones escritas como (request: Request) => Response: Vercel Functions, Supabase Edge Functions, HonowrapFetchHandler, abajo.Al lanzar
Manejadores de AWS Lambda que reciben eventos de API Gateway o de Function URLUn adaptador está Planeado. Hoy: la entrada OTLP.Planeado
Bun, Deno y Cloudflare WorkerswrapFetchHandler solo usa APIs estándar de la web y AsyncLocalStorage. No se prueba en estos al lanzar.Planeado
api/checkout.ts
import { init, wrapFetchHandler } from '@sypnia/node';

init({ project: process.env.SYPNIA_PROJECT_KEY, service: 'shop-api' });

export default wrapFetchHandler(async (request: Request) => {
  const order = await createOrder(await request.json());
  return Response.json(order);
});

wrapFetchHandler traza la petición como cualquier otra y envía sus eventos después de la respuesta. Donde la plataforma ofrece una forma de seguir trabajando tras la respuesta (waitUntil), la usa. Donde no, espera máximo flushBudgetMs (50 ms) antes de devolver la respuesta; un envío que tarda más sigue en segundo plano y puede perderse si la plataforma congela la función.

Una función que se congela entre invocaciones no corre temporizadores. Si no usas wrapFetchHandler, llama a await flush() antes de devolver.

Costo

Presupuestos con los que el SDK se compromete:

  • Agrega menos de 1 milisegundo a una petición, en la mediana, para una petición con hasta 20 spans.
  • Nunca retrasa una respuesta en un servidor de larga vida: los eventos se envían en segundo plano, en lotes.
  • Un fallo dentro del SDK nunca llega a tu código: cada punto de entrada está envuelto, y un envío que falla se reintenta y luego se descarta, con un aviso por minuto como máximo.

Sigue con

  • Next.js

    Una sola configuración para el cliente y el servidor.
  • OpenTelemetry

    Para todo backend que no sea Node.
  • Trazas

    Qué es una traza y cómo se une.

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