# 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: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/sdks/node/

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`](https://docs.sypnia.com/es/sdks/nextjs), 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**

```bash
npm install @sypnia/node
```

**pnpm**

```bash
pnpm add @sypnia/node
```

**yarn**

```bash
yarn add @sypnia/node
```

**bun**

```bash
bun add @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`

```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,
});
```

**Alojamiento propio**

`src/instrument.ts`

```ts
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,
});
```

`src/server.ts`

```ts
import './instrument';
import express from 'express';

const app = express();
app.post('/api/checkout', checkout);
app.listen(3000);
```

`.env`

```bash
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.

> **Nota: La llave es una llave de ingesta**
>
> El servidor usa una llave de ingesta (`spk_…`), igual que el navegador. Solo puede enviar. Nunca le des a un SDK de servidor un token de API (`sps_…`): la ingesta lo rechaza.

## 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é                             | 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](https://docs.sypnia.com/es/sdks/opentelemetry).

**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](https://docs.sypnia.com/es/sdks/browser).

## `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](https://docs.sypnia.com/es/reference/event-schema).

## 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**

`src/server.ts`

```ts
import { reportError } from '@sypnia/node';

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

**Fastify**

`src/server.ts`

```ts
import { reportError } from '@sypnia/node';

app.addHook('onError', async (request, reply, error) => {
  reportError(error);
});
```

**Koa**

`src/server.ts`

```ts
import { reportError } from '@sypnia/node';

app.on('error', (error) => reportError(error));
```

**Hono**

`src/server.ts`

```ts
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.

`src/auth-middleware.ts`

```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](https://docs.sypnia.com/es/sdks/identifying-people).

### `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`

```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`

```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 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`](https://docs.sypnia.com/es/sdks/nextjs).                                                   | **\[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](https://docs.sypnia.com/es/sdks/opentelemetry).   | **\[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]**  |

`api/checkout.ts`

```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
