Solución de problemas
Qué revisar cuando no llega nada, cuando un bloqueador de anuncios, CORS o una política de seguridad de contenido bloquean las peticiones, cuando los source maps no aplican y cuando las sesiones parecen duplicadas.
En esta página
- Empieza aquí: la lista de chequeo
- Enciende debug
- Mira la petición
- Lee la respuesta, no solo el estado
- Mira en el lugar correcto
- Alojamiento propio: pregúntale al motor
- No llega nada
- Desde un servidor Node
- Orígenes y CORS
- Bloqueadores de anuncios
- Política de seguridad de contenido
- Los source maps no aplican
- Sesiones duplicadas o partidas
- Una traza no se une
- Falta una grabación
- Si sigues atascado
Esta página es para cuando el SDK está instalado y falta algo. Cubre los tres SDK, para el motor de código abierto y para Sypnia Cloud; los pasos que aplican solo a uno están marcados.
Empieza aquí: la lista de chequeo
Hazlos en orden. La mayoría de los casos termina en uno de los cuatro primeros.
Enciende debug
Pon
debug: trueeninit(enwithSypniapara Next.js) y recarga.Deberías verEn la consola del navegador, una línea[sypnia] startedcon el prefijo de la llave del proyecto, el endpoint, el entorno y la versión, y luego una línea por cada evento. Si ves[sypnia] off:, lo sigue el motivo.Mira en el lugar correcto
En Sypnia, elige el entorno que envía tu app. Una app que corre en
localhostcon el fragmento del inicio rápido envíadevelopment, y las listas muestranproductionpor defecto. Las sesiones y los números están completos en menos de 10 minutos; un problema nuevo aparece en menos de 2 minutos.Alojamiento propio: pregúntale al motor
Motor En la máquina que corre el motor:
Terminal sypnia doctorDeberías verUna línea por cada pieza de la que depende el motor (ajustes, base de datos, almacenamiento, dirección pública, proveedor de IA, webhook, reloj), cada unaok, yall checks passed. Una línea que diceFAILnombra el ajuste que hay que cambiar.sypnia doctorrevisa el motor, no tu app. Si pasa y los eventos siguen sin verse, la causa está en esta página.
No llega nada
| Qué ves | Causa | Qué hacer |
|---|---|---|
Ninguna petición, y [sypnia] off: no project | project está vacío. Suele ser una variable de entorno que no existe en el paquete del navegador. | Imprime el valor que pasas. En Vite la variable debe empezar por VITE_; en Next.js usa withSypnia. |
Ninguna petición, y [sypnia] off: opted out | localStorage tiene sypnia:off. Alguien llamó a optOut(), o lo dejó una configuración de pruebas. | Llama a optIn(), o borra la clave. |
Ninguna petición, y [sypnia] off: disabled | enabled: false. | Revisa la condición que pasas. |
| Ninguna petición solo en algunas páginas | La ruta está en ignoreRoutes. | Quítala de la lista. |
| Ninguna línea en la consola | init nunca corrió: el archivo no se importa, o la etiqueta script no tiene data-project y nada llama a init. | Importa el archivo primero en tu punto de entrada. |
La petición sale en rojo: net::ERR_BLOCKED_BY_CLIENT | Un bloqueador de anuncios o una extensión de privacidad. | Mira la sección Bloqueadores de anuncios. |
La petición sale en rojo: bloqueada por Content-Security-Policy | La política de tu sitio no permite la dirección. | Mira la sección Política de seguridad de contenido. |
401 unauthorized | La llave no existe o está revocada, o es de otro motor. | Copia la llave otra vez. Una llave de Sypnia Cloud no sirve en un motor con alojamiento propio, ni al revés. |
403 wrong_credential | Se usó un token de API (sps_…) o el token raíz como project. | Usa la llave de ingesta (spk_…). Revoca el token: quedó expuesto. |
403 origin_not_allowed | El proyecto lista orígenes permitidos y el de esta página no está. | Mira la sección Orígenes y CORS. |
413 payload_too_large | No viene del SDK: mantiene los lotes muy por debajo del límite. Un proxy intermedio está reescribiendo el cuerpo. | Revisa el proxy. |
429 rate_limited | Una dirección envía demasiado rápido con esta llave. | El SDK espera y reintenta solo. Si sigue, busca un bucle que lanza errores o llama a track. |
200 con dropped_reasons: { limit_reached: … } | El proyecto llegó a un límite. | Mira Muestreo y cuotas. |
200 con dropped_reasons: { invalid: … } | A un evento le falta un campo obligatorio. Desde un SDK oficial es un error nuestro; desde tu propio cliente, compáralo con el esquema de eventos. | Repórtalo con el evento que imprime debug. |
200, nada descartado, nada en Sypnia | Entorno equivocado, proyecto equivocado, o hace menos de 10 minutos. | El paso 4 de arriba. |
| Alojamiento propio: la petición falla con un error de conexión o de certificado | endpoint no es la URL base pública del motor, o el motor no es alcanzable desde internet por HTTPS. | Abre <endpoint>/healthz en un navegador. Corre sypnia doctor --only address. |
Desde un servidor Node
| Qué ves | Causa | Qué hacer |
|---|---|---|
No se imprime ningún server_request con debug: true | init corrió después de crear el servidor, o en otro proceso. | Importa ./instrument en la primera línea del archivo de entrada. |
Se imprimen eventos, y luego send failed | El servidor no alcanza el endpoint: un firewall, un proxy, el DNS. | curl -i <endpoint>/healthz desde la misma máquina. |
| Nada desde una función serverless | La función se congeló antes del envío. | Usa wrapFetchHandler, o await flush() antes de devolver. |
| Solo algunas rutas | Los archivos estáticos, OPTIONS e ignoreRoutes no se trazan. | Es lo esperado. |
Orígenes y CORS
A tres cosas distintas se les llama problemas de CORS.
1. La ingesta rechaza el origen de tu página. La ingesta responde CORS para cualquier origen por su cuenta; no configuras nada en ella. La excepción es un proyecto que lista orígenes permitidos (settings.allowed_origins): entonces los demás orígenes reciben 403 origin_not_allowed. Agrega el origen, con su esquema y su puerto, o vacía la lista:
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"allowed_origins": ["https://shop.example", "http://localhost:5173"]}}'Las direcciones de vista previa de los constructores de apps y de los proveedores cambian con cada despliegue. O dejas la lista vacía, o no esperes que las vistas previas reporten.
2. Tu propia API rechaza los encabezados de traza. Si tu API está en otro origen y figura en traceTargets, el navegador le pregunta primero si traceparent y x-sypnia-session están permitidos. Si tu API dice que no, tus propias llamadas fallan. Permite ambos encabezados en la respuesta CORS de la API, o quita la API de traceTargets (usa recordTargets para seguir registrando sus llamadas sin encabezados).
Access-Control-Allow-Headers: content-type, authorization, traceparent, x-sypnia-session3. Un motor con alojamiento propio detrás de tu propio proxy. Deja que el motor responda OPTIONS él mismo. Si el proxy agrega sus encabezados CORS encima de los del motor, los navegadores rechazan la respuesta porque el encabezado aparece dos veces.
Bloqueadores de anuncios
Algunos bloqueadores de anuncios y extensiones de privacidad bloquean por nombre de host las peticiones a servicios de monitoreo. La app sigue funcionando: el SDK falla en silencio. Pierdes las sesiones de esos visitantes.
La solución es enviar por tu propio dominio. Agrega a tu sitio una ruta que reenvíe a la ingesta, y pon endpoint con esa ruta. Una ruta del mismo origen de la página es un endpoint válido.
Next.js
const nextConfig: NextConfig = {
async rewrites() {
return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
},
};init({ endpoint: '/_sy' });nginx
location /_sy/ {
proxy_pass https://ingest.sypnia.com/;
proxy_set_header Host ingest.sypnia.com;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_ssl_server_name on;
}init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', endpoint: '/_sy' });Conserva X-Forwarded-For: los límites de frecuencia son por dirección, y sin él todos tus visitantes comparten la de tu proxy. Con la etiqueta script, sirve sdk.js por la misma ruta: src="/_sy/v1/sdk.js" y data-endpoint="/_sy". En un motor con alojamiento propio, reenvía a la URL base de tu motor.
Un bloqueador que bloquea por la forma de la petición y no por el host no se puede esquivar, y no se debe: ese visitante pidió que no lo midan.
Política de seguridad de contenido
Si tu sitio envía una Content-Security-Policy, permite a Sypnia en ella. Reemplaza el host por el de tu motor si tienes alojamiento propio, o por 'self' si envías por tu propio dominio.
| Directiva | Agrega | Hace falta para |
|---|---|---|
connect-src | https://ingest.sypnia.com | Enviar eventos y grabaciones. |
script-src | https://ingest.sypnia.com | Solo la etiqueta script. No hace falta con el paquete de npm. |
El SDK no usa scripts en línea, ni eval, ni workers.
Los source maps no aplican
Una pila sigue mostrando checkout-3f9c.js:1:48211 en vez de src/checkout/checkout.tsx:142.
| Revisa | Cómo | Arreglo |
|---|---|---|
| La versión del evento es la versión para la que subiste. | Abre una ocurrencia del problema y lee su versión. Compárala con --release en tu compilación. Un hash de commit completo y sus primeros 7 caracteres son versiones distintas. | Usa una sola expresión para ambos. En Next.js, withSypnia lo hace. |
| El evento tiene versión. | debug: true imprime release al arrancar. | Pasa release a init. |
| Los source maps llegaron. | curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" -H "Authorization: Bearer $SYPNIA_API_TOKEN": cada archivo debe decir "uploaded": true. | Corre la subida otra vez; se salta lo que ya está. |
| Las rutas coinciden. | En esa lista, url_path debe ser la ruta desde la que el navegador carga el archivo: /assets/checkout-3f9c.js. | Pon --url-prefix en sypnia sourcemaps upload. |
| Los source maps se generaron. | Tu empaquetador debe escribir archivos .map: build.sourcemap: 'hidden' en Vite, devtool: 'hidden-source-map' en webpack. | Enciéndelos, y bórralos después de la subida. |
| La subida corrió antes de que el despliegue quitara los archivos. | Lee el registro de la compilación: la subida imprime cuántos source maps encontró. | Sube justo después de empaquetar. |
| El fallo es anterior a la subida. | Los source maps aplican desde la siguiente ocurrencia del problema. | Espera la siguiente, y pide un análisis nuevo. |
| Un source map pesa más de 64 MB. | La subida lo lista como omitido. | Divide el paquete. |
| La pila es del servidor de una app Next.js. | — | Los source maps del servidor están Planeado. |
La agrupación nunca depende de los source maps: el problema es el mismo problema antes y después.
Sesiones duplicadas o partidas
Una visita aparece como varias sesiones.
| Causa | Cómo saberlo | Qué hacer |
|---|---|---|
| El navegador bloquea el almacenamiento (modo privado en algunos navegadores, ajustes estrictos, una vista web incrustada sin almacenamiento). | debug: true imprime storage unavailable, session kept in memory. Cada carga completa de página es entonces una sesión nueva. | Nada en el SDK puede arreglarlo. Una app de una sola página no se ve afectada, porque no recarga. |
Dos orígenes. shop.example y app.shop.example, o http y https, tienen almacenamiento separado. | Las sesiones vienen en pares con hosts distintos. | Sirve la app desde un solo origen. Las sesiones no se pueden compartir entre orígenes al lanzar. |
| La página está incrustada en un marco de otro sitio. | Sesiones desde el sitio que la incrusta. | Es lo esperado: un marco tiene su propio almacenamiento. |
| 30 minutos sin actividad. | El hueco entre las dos sesiones es de más de 30 minutos. | Es lo esperado. |
Se identificó a otra persona, o se llamó a identify(null). | Las sesiones tienen personas distintas. | Es lo esperado. No llames a identify(null) en cada carga de página antes de saber quién tiene sesión iniciada. |
| El SDK se carga dos veces desde dos compilaciones distintas. | Dos líneas [sypnia] started. | La segunda no hace nada, por diseño: una sola sesión. Si ves eventos dobles, repórtalo. |
| Pruebas o bots. | Muchas sesiones de una sola página desde la misma clase de dispositivo. | Corre las pruebas con enabled: false, o con localStorage.setItem('sypnia:off', '1'). |
Una traza no se une
La llamada del navegador y la petición del servidor aparecen como dos trazas.
- La API está en otro origen y no figura en
traceTargets: el encabezado no se envía. Agrégala. - El CORS de la API no permite
traceparent: mira arriba. - Un proxy o una pasarela intermedia quita o reemplaza
traceparent. Déjalo pasar. - El navegador y el servidor envían a proyectos distintos o con valores distintos de
environment. Una traza une un proyecto y un entorno. - El SDK del servidor arrancó después que el servidor. Importa
./instrumentprimero.
Falta una grabación
- La sesión no estaba en la parte muestreada y nada salió mal en ella. Es lo normal: mira Muestreo y cuotas.
- La sesión sigue activa. Una grabación se puede ver cuando la sesión lleva 2 minutos inactiva, o terminó.
- La ruta está en
replay.blocked_routesdel proyecto o enreplay.blockedRoutes. - El proyecto llegó a su límite de grabaciones. La línea de tiempo de la sesión lo dice.
replay: falseeninit.- A tu token le falta el permiso
replay: ves que existe una grabación y no puedes abrirla.
Si sigues atascado
Reúne esto antes de preguntar: el nombre y la versión del SDK, la salida de la consola con debug: true desde el arranque hasta el primer envío, el estado y el cuerpo de la petición a la ingesta y, con alojamiento propio, la salida de sypnia doctor. Quita el token de API si aparece alguno; la llave de ingesta es pública. Dónde preguntar está en Soporte para Sypnia Cloud y en Contribuir para el motor de código abierto.