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.
En esta página
- Instalar
- Comprueba que funciona
- Qué se traza sin escribir código
- Cuándo falló una llamada
- Peticiones que nunca terminan
- Unir el navegador con el servidor
- init(options)
- Errores
- Las funciones que llamas tú
- reportError(error)
- identify(who)
- span(name, fn, attrs?)
- flush(timeoutMs?) y shutdown(timeoutMs?)
- wrapFetchHandler(handler)
- Apagado ordenado
- Serverless y otros entornos
- Costo
- 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/nodepnpm
pnpm add @sypnia/nodeyarn
yarn add @sypnia/nodebun
bun add @sypnia/nodeCrea un archivo que arranque Sypnia, e impórtalo antes que cualquier otra cosa en el archivo de entrada de tu servidor.
Sypnia Cloud
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,
});Alojamiento propio
import { init } from '@sypnia/node';
init({
project: process.env.SYPNIA_PROJECT_KEY,
endpoint: 'https://sypnia.example.com',
service: 'shop-api',
environment: process.env.SYPNIA_ENVIRONMENT ?? 'production',
release: process.env.SYPNIA_RELEASE,
});import './instrument';
import express from 'express';
const app = express();
app.post('/api/checkout', checkout);
app.listen(3000);SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
SYPNIA_ENVIRONMENT=production
SYPNIA_RELEASE=4f2a91cUsa 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
- Arranca tu servidor con
debug: trueeninit. - Llama a cualquier ruta:
curl -i http://localhost:3000/api/checkout -X POST. - La consola imprime un evento
server_requestcon el método, la ruta, el estado y sus spans, y luegosent 1 event (200).
Qué se traza sin escribir código
| Qué | Cubre | Se convierte en |
|---|---|---|
| Peticiones entrantes | Toda 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 salientes | fetch, 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 Postgres | El 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 PostgREST | Se reconocen entre las llamadas salientes por su ruta (/rest/v1/…). | Un span de clase db: SELECT orders, INSERT orders, CALL create_order. |
| Errores | Los 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:
| Encabezado | Se lee como |
|---|---|
traceparent | El 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-session | El 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ón | Tipo | Por defecto | Qué hace |
|---|---|---|---|
project | string | process.env.SYPNIA_PROJECT_KEY | La llave de ingesta, spk_…. Sin ella el SDK no hace nada e imprime un solo aviso. |
endpoint | string | process.env.SYPNIA_ENDPOINT, si no 'https://ingest.sypnia.com' | A dónde enviar. La URL base de un motor con alojamiento propio. |
service | string, hasta 80 caracteres | process.env.SYPNIA_SERVICE, si no 'server' | El nombre de este servicio en las trazas. |
environment | string, de 1 a 40 caracteres | process.env.SYPNIA_ENVIRONMENT, si no 'production' | El entorno. Usa los mismos nombres que el frontend. |
release | string, hasta 40 caracteres | process.env.SYPNIA_RELEASE, si no ninguno | La versión (release). Usa el commit corto de git. |
enabled | boolean | true | false deja el SDK sin efecto. |
debug | boolean | false | Imprime 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) => string | la regla incluida | Tu 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.outgoing | boolean | true | Spans para las llamadas HTTP salientes. |
capture.db | boolean | true | Spans para pg, y nombres para las llamadas a Supabase y PostgREST. |
capture.consoleErrors | boolean | true | Reporta como fallo un console.error durante una petición. |
capture.uncaught | boolean | true | Reporta excepciones sin capturar y rechazos sin manejar. |
propagate | boolean | true | Agrega traceparent a las llamadas salientes. |
slowRequestMs | number | 20000 | Cuándo se reporta como parcial una petición que sigue corriendo. 0 lo apaga. |
flushBudgetMs | number | 50 | Lo máximo que el SDK espera un envío al final de una invocación serverless. |
beforeSend | (event) => event | null | ninguno | Se 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ódigo | Cómo aparece |
|---|---|
| Una excepción que nadie capturó, o un rechazo sin manejar | Un 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 fallo | Un fallo llamado HTTP 500, con la ruta. |
console.error mientras se atiende una petición | Un 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
import { reportError } from '@sypnia/node';
// después de todas las rutas
app.use((error, req, res, next) => {
reportError(error);
next(error);
});Fastify
import { reportError } from '@sypnia/node';
app.addHook('onError', async (request, reply, error) => {
reportError(error);
});Koa
import { reportError } from '@sypnia/node';
app.on('error', (error) => reportError(error));Hono
import { reportError } from '@sypnia/node';
app.onError((error, c) => {
reportError(error);
return c.json({ error: 'internal_error' }, 500);
});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.
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.
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:
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 corre | Qué hacer | Estado |
|---|---|---|
| Un servidor Node de larga vida, Node 20 o más nuevo | import './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, Hono | wrapFetchHandler, abajo. | Al lanzar |
| Manejadores de AWS Lambda que reciben eventos de API Gateway o de Function URL | Un adaptador está Planeado. Hoy: la entrada OTLP. | Planeado |
| Bun, Deno y Cloudflare Workers | wrapFetchHandler solo usa APIs estándar de la web y AsyncLocalStorage. No se prueba en estos al lanzar. | Planeado |
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
- Una sola configuración para el cliente y el servidor.
- Para todo backend que no sea Node.
- Qué es una traza y cómo se une.