Agrupación de problemas
Cómo las fallas se vuelven problemas, con el algoritmo exacto de la huella calculado a mano, la traducción de pilas con source maps, la regla que hace de una solicitud un solo problema entre navegador y servidor, los estados de un problema y qué dispara una alerta.
Un problema es un grupo de fallas con una sola causa. Esta página explica cómo decide el motor que dos fallas son la misma, cómo convierte una pila minificada en tus propios archivos y líneas, y cómo pasa un problema de un estado a otro. Es el diseño detrás de Problemas.
La agrupación la hace la vía rápida: el lector que revisa cada segmento nuevo en busca de fallas cada 30 segundos. Flujo de datos muestra dónde está.
De una falla a un problema
(1) Qué cuenta como falla. La vía rápida mira cuatro tipos de línea e ignora todas las demás.
| Línea | Es una falla cuando | Tipo | La huella viene de |
|---|---|---|---|
error (navegador) | Siempre | error | El SDK: fp |
server_error | Siempre | error, o failed_call cuando src es span | El SDK: fp. El motor la calcula para OTLP |
server_request | partial es true y no existe el registro completo de la misma traza | timeout | El SDK: fp |
request (navegador) | Sin respuesta, 400, o 500 o más | failed_call | El motor: ningún campo del SDK la trae |
Un 401, 403, 404, 409 o 422 no es una falla. Tampoco un clic de rabia ni una página lenta. Eso lo cuenta la consolidación y nunca llega a este código.
(2), (3) y (4) son las tres secciones que siguen. (5) es la traducción con source maps.
La huella
Una huella son 16 caracteres hex. Las fallas con la misma huella, en el mismo proyecto y entorno, son el mismo problema.
Se calcula donde ocurre la falla, en el SDK, para que el SDK también pueda descartar una repetición del mismo error dentro de 5 segundos. El motor lleva el mismo algoritmo para los casos en que ningún SDK hizo el trabajo: excepciones de OTLP y llamadas fallidas del navegador. Los dos deben dar los mismos bytes para la misma entrada, así que el algoritmo queda escrito aquí con exactitud, y los mismos vectores de prueba corren en TypeScript y en Rust.
El algoritmo
Para un error, tres partes unidas con |:
nombre | mensaje normalizado | función@archivo del primer marco de tu propio código-
name: el nombre del error.Errorcuando no hay. -
El mensaje, normalizado, en este orden:
Paso Reemplazar Por 1 URLs <url>2 Rutas de fragmentos compilados, como /_next/static/chunks/…<chunk>3 UUIDs <uuid>4 Textos entre comillas de hasta 200 caracteres "…"5 Secuencias de 12 o más caracteres hex <hex>6 Números #7 Espacios seguidos un espacio 8 Todo lo que pase de los primeros 300 caracteres nada -
El marco superior: se leen las primeras 30 líneas de la pila, en la forma de V8 (
at fn (file:line:col)) o la de Gecko (fn@file:line:col). Se toma el primer marco cuyo archivo no sea ruido. Ruido esnode_modules, los fragmentos del propio framework,react-dom,scheduler,node:internaly<anonymous>. Si todos los marcos son ruido, se toma el primero. Luego se limpia el archivo: se quitan el origen, la consulta y el fragmento; se quita un hash de compilación de la forma-seguido de 8 o más caracteres hex; se corta todo lo anterior a la carpeta de compilación. La parte esfunción@archivo, o vacía cuando no hay pila.
Si el framework le dio al error un digest de 6 o más dígitos, la huella es el hash de digest: más el digest, porque ese id ya es estable.
Para una llamada fallida, la llamada, cómo falló y la solicitud en la que ocurrió:
call | nombre del span | estado o código de error | MÉTODO | rutaPara un tiempo agotado: timeout | MÉTODO | ruta.
El hash, hash64, es FNV-1a de 32 bits, corrido dos veces sobre el mismo texto con dos semillas distintas; los dos resultados se escriben con 8 caracteres hex cada uno y se unen.
| Valor | |
|---|---|
| Semilla de la primera mitad | 0x811c9dc5 |
| Semilla de la segunda mitad | 0x050c5d1f |
| Primo | 0x01000193 |
| Un paso | h = (h XOR unidad) × primo, conservando los 32 bits bajos |
| Una unidad | Una unidad de código UTF-16 del texto |
Fíjate en que la función no recibe proyecto ni hora: una huella depende solo de la falla.
const PRIME: u32 = 0x0100_0193;
const SEED_A: u32 = 0x811c_9dc5;
const SEED_B: u32 = 0x050c_5d1f;
/// FNV-1a de 32 bits sobre unidades de código UTF-16. Debe coincidir con los SDK bit por bit.
fn fnv1a_utf16(text: &str, seed: u32) -> u32 {
text.encode_utf16()
.fold(seed, |hash, unit| (hash ^ u32::from(unit)).wrapping_mul(PRIME))
}
/// 16 caracteres hex: dos hashes de 32 bits del mismo texto con semillas distintas.
pub fn hash64(text: &str) -> Fingerprint {
Fingerprint::from_halves(fnv1a_utf16(text, SEED_A), fnv1a_utf16(text, SEED_B))
}
pub fn error_fingerprint(name: Option<&str>, message: &str, stack: Option<&str>, digest: Option<&str>) -> Fingerprint {
if let Some(digest) = digest.filter(|d| d.len() >= 6 && d.bytes().all(|b| b.is_ascii_digit())) {
return hash64(&format!("digest:{digest}"));
}
let frame = stack
.and_then(top_frame) // primer marco de tu propio código, V8 o Gecko
.map(|f| format!("{}@{}", f.function, normalize_frame_file(&f.file)))
.unwrap_or_default();
hash64(&format!(
"{}|{}|{}",
name.unwrap_or("Error"),
normalize_message(message),
frame,
))
}
pub fn call_fingerprint(span_name: &str, code: &str, method: &str, route: &str) -> Fingerprint {
hash64(&format!("call|{span_name}|{code}|{}|{route}", method.to_ascii_uppercase()))
}
pub fn timeout_fingerprint(method: &str, route: &str) -> Fingerprint {
hash64(&format!("timeout|{}|{route}", method.to_ascii_uppercase()))
}Calculada a mano
La página de pago de la tienda lanza esto cuando el cobro es rechazado:
ApiError: POST /api/checkout failed with 400 (amount_required)
at o (https://shop.example/assets/checkout-3f9c.js:1:48211)
at async HTMLButtonElement.<anonymous> (https://shop.example/assets/checkout-3f9c.js:1:49002)| Paso | Resultado |
|---|---|
| (1) Nombre | ApiError |
(2) Mensaje, normalizado. La regla 6 convierte 400 en #; nada más coincide | POST /api/checkout failed with # (amount_required) |
(3) Marco superior. El primer marco, o, es tu propio código. Su archivo pierde el origen, la línea y la columna. -3f9c tiene cuatro caracteres, menos de los ocho que necesita un hash de compilación, así que se queda | o@/assets/checkout-3f9c.js |
| (4) Unido | ApiError|POST /api/checkout failed with # (amount_required)|o@/assets/checkout-3f9c.js |
(5) hash64, primera mitad, semilla 0x811c9dc5 | 15228057 |
(5) hash64, segunda mitad, semilla 0x050c5d1f | 93228d19 |
| Huella | 1522805793228d19 |
Los dos primeros pasos de la primera mitad, para comparar una implementación: el texto empieza con A (unidad 0x41) y p (0x70).
h0 = 0x811c9dc5
h1 = (h0 XOR 0x41) × 0x01000193 mod 2^32 = 0x811c9d84 × 0x01000193 = 0xc40bf6cc
h2 = (h1 XOR 0x70) × 0x01000193 mod 2^32 = 0xc40bf6bc × 0x01000193 = 0x5ad569f4
…
h86 = 0x15228057Y la falla que hay detrás en el servidor, la llamada que el servicio de pagos rechazó:
| Falla | Texto al que se le hace hash | Huella |
|---|---|---|
| La llamada fallida del servidor | call|POST /v1/payments|400|POST|/api/checkout | 88a44b15205cb153 |
| Si esa solicitud se hubiera quedado colgada | timeout|POST|/api/checkout | c405205e99c5aa6c |
88a44b15205cb153 es el problema de la historia de ejemplo. Por qué es ese y no el del navegador es la sección que sigue.
Una solicitud, un problema
(2) en la primera figura. Cuando el cliente hace clic en Pagar, se reportan tres fallas de la misma solicitud:
- la llamada del servidor al servicio de pagos respondió
400(server_error, de@sypnia/node); - la llamada de la página a
POST /api/checkoutrespondió400(request, de@sypnia/browser); - la página lanzó
ApiError(error, de@sypnia/browser).
Tres problemas por un clic serían ruido. La regla: la falla más profunda de una traza es el problema; lo que vio la persona es evidencia dentro de él.
Cómo lo aplica la vía rápida:
| Falla | Qué hace la vía rápida |
|---|---|
| Una falla del servidor, con id de traza (1) | Es el problema. Entra una fila a trace_failures: «la traza 7c2e9a4b… es del problema prb_8f3k2m9x4q7w», por 48 horas. Si la misma traza tiene dos fallas del servidor, gana la del span más profundo. |
Un request fallido del navegador, con id de traza (2) | Se busca la traza en trace_failures. Está: es evidencia de ese problema. No suma ocurrencia; suma la persona y la sesión si el registro del servidor no las traía. No está, y el proyecto ha enviado datos del servidor: se retiene 15 segundos en held_failures y se busca otra vez. Sigue sin estar, o el proyecto solo tiene el SDK del navegador: es su propio problema. |
Un error del navegador en el mismo lote y sesión que un request fallido, máximo 2 segundos después (3) | Sigue a esa solicitud: evidencia si la solicitud es evidencia, y si no, parte del problema de la solicitud. |
Un error del navegador sin una solicitud fallida antes | Su propio problema. Son la mayoría de los errores del navegador: un TypeError en tu código no tiene una solicitud detrás. |
La retención existe porque las dos mitades viajan por separado. El registro del servidor casi siempre llega primero, porque el servidor envía cuando termina la solicitud y el navegador espera hasta 10 segundos para enviar su lote. Los 15 segundos cubren el orden contrario. Son parte del presupuesto de 2 minutos calculado en Flujo de datos, y solo los gastan los proyectos que envían datos del servidor.
Un proyecto que solo tiene el SDK del navegador recibe como problema la llamada fallida de la página, tal como dice Problemas.
Traducción con source maps
Un navegador reporta la pila del código que ejecutó: minificado, en una línea, con nombres como o. Los source maps la devuelven a tus archivos.
(5) en la primera figura. La traducción ocurre después de que el problema existe y antes de que el agente lo lea. Nunca cambia la huella: la agrupación usa el marco minificado, así que un problema no se parte cuando los mapas llegan tarde o faltan.
| Regla | |
|---|---|
| Cuándo | Cuando un problema nace o vuelve; otra vez cuando los mapas de su versión se suben después de la falla; y para la primera ocurrencia en cada versión nueva |
| Qué versión | El ver de la ocurrencia. Sin ver no hay traducción |
| Encontrar el mapa | sourcemaps/<release>/index.json relaciona cada archivo compilado con su mapa. Los empaquetadores nombran los mapas sin relación con los fragmentos, así que adivinar <archivo>.map es solo el último recurso |
| Marcos | Los primeros 30. Formas de V8 y de Gecko. Un marco sin mapa se queda como está |
| Resultado | sample.stack_original, la pila con archivo:línea:columna y nombres de función originales, y where: el archivo, la línea y la función del primer marco de tu propio código |
| Límites | Una caché de 50 mapas o 200 MB; un mapa de más de 64 MB se salta; 60 segundos para el paso |
| Si falla | El problema conserva su pila minificada. El paso nunca bloquea un problema ni una alerta |
Para el error de pago, el resultado es:
ApiError: POST /api/checkout failed with 400 (amount_required)
at confirmPayment (src/checkout/checkout.tsx:142:11)
at async onPayClick (src/checkout/PayButton.tsx:31:5)De este paso se expone un número: problemas traducidos ÷ problemas que tenían versión y pila, en las últimas 24 horas, que muestra sypnia doctor. La razón es un incidente del sistema del que sale esto: durante seis días no se tradujo ningún error, porque una opción de compilación rompió el lector de mapas, y nadie lo notó. Una línea de log no es un número de salud.
Los estados de un problema
Un problema tiene un estado, open, resolved o ignored, y un problema abierto puede llevar marcas: nuevo, creciendo, volvió. Juntos son los estados de abajo.
El motor decide una transición con una sola función pura. Recibe el problema como estaba antes de este segmento y como queda después, y responde qué pasó. Fíjate en que no puede escribir nada: quien la llama escribe la transición, la alerta y la fila del registro en una transacción, así que una transición nunca se puede anotar dos veces.
#[derive(Debug, PartialEq)]
pub enum Transition {
Born,
CameBack,
Growing { from: u32, to: u32 },
Quiet, // se cuenta, no hay nada que avisar
}
pub fn transition(
before: Option<&ProblemState>,
after: &ProblemState,
seen: &Seen, // lo que agregó este segmento: versiones, personas
rules: &GrowingRule, // factor 2, min_people 5, salvo que el proyecto los cambie
) -> Transition {
let Some(before) = before else {
return Transition::Born;
};
match before.status {
Status::Ignored => Transition::Quiet,
Status::Resolved => {
// «Pestañas viejas»: si se nombró la versión del arreglo, solo reabre una falla en esa versión o en una posterior.
let reopens = match &before.resolved_in_release {
Some(fix) => seen.releases.iter().any(|r| r.is_same_or_later_than(fix)),
None => true,
};
if reopens { Transition::CameBack } else { Transition::Quiet }
}
Status::Open => {
let threshold = before
.people_at_last_alert
.saturating_mul(rules.factor)
.max(rules.min_people);
if after.people >= threshold && after.people > before.people_at_last_alert {
Transition::Growing { from: before.people_at_last_alert, to: after.people }
} else {
Transition::Quiet
}
}
}
}Sigue el ejemplo de Problemas por ella. El problema nace con 1 persona, y people_at_last_alert queda en 1. Con 3 personas el umbral es max(1 × 2, 5) = 5: sin novedad. Con 5 personas: creciendo, y people_at_last_alert queda en 5. El siguiente umbral es 10, luego 20.
«Posterior», para una versión, significa que el motor la vio por primera vez al mismo tiempo que la versión del arreglo o después. El motor no compara los textos de las versiones: un commit corto de git no tiene orden.
Qué escribe una transición
Todo en la misma transacción que además marca el segmento como revisado:
| Transición | problems | Alerta | El agente |
|---|---|---|---|
| Nace | Una fila nueva, status = open, people_at_last_alert = people | problem.new | Traducir la pila y luego analizar |
| Volvió | status = open, regressed = true; resolved_at y resolved_by quedan como historia | problem.regressed | Traducir la pila y analizar de nuevo |
| Creciendo | growing_until = ahora + 24 h, people_at_last_alert = people | problem.growing | Analizar de nuevo, dentro del límite diario por problema |
| Sin novedad | Solo contadores y last_seen | Ninguna | Nada |
Qué dispara una alerta
Para los problemas, exactamente las tres transiciones de arriba, y solo cuando la regla del proyecto para ese tipo está encendida en el entorno del problema. Por defecto las tres están encendidas solo para production.
Cada fila de alerta tiene un dedupe_key con índice único, y eso hace que «un problema es una alerta» sea una propiedad de la base de datos y no un deseo:
| Alerta | dedupe_key | Para que |
|---|---|---|
problem.new | problem.new:<problem id> | Un problema sea nuevo una vez en su vida |
problem.regressed | problem.regressed:<problem id>:<resolved_at> | Una vez por cada vez que se resolvió |
problem.growing | problem.growing:<problem id>:<people at last alert> | Una vez por cada escalón: 5, 10, 20 |
La alerta se inserta con released_at vacío y release_by puesto a 100 segundos después de que la falla llegó a la ingesta. Se libera cuando el agente escribe la frase, o al llegar release_by, lo que ocurra primero. Liberar significa: llenar released_at, escribir el título (la frase, o el título técnico) y entregarla a cada salida de alertas. El proceso del agente muestra esa entrega, y Formas de despliegue muestra las salidas.
Los demás tipos de alerta (disponibilidad, una página que se volvió lenta, una ruta de la API que falla, uso, el propio motor) los producen la pasada y la consolidación a partir de números, no este código. Sus reglas están en Alertas y el resumen diario.
Un problema, como lo devuelve la API
Después de tres personas y cinco fallas, GET /v1/problems/pay-button-does-nothing responde con la fila de problems, su análisis y sus enlaces:
{
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing",
"fingerprint": "88a44b15205cb153",
"kind": "failed_call",
"origin": "server",
"status": "open",
"regressed": false,
"title": "createPayment answered 400 in POST /api/checkout",
"environment": "production",
"route": "/checkout",
"where": { "file": "src/checkout/checkout.tsx", "line": 142, "function": "confirmPayment" },
"first_seen": "2026-03-12T09:12:04Z",
"last_seen": "2026-03-12T10:31:47Z",
"first_release": "4f2a91c",
"last_release": "4f2a91c",
"occurrences": 5,
"people": 3,
"sessions": 3,
"resolved_at": null,
"resolved_by": null,
"resolved_in_release": null,
"note": null,
"analysis": {
"status": "ready",
"sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
"confidence": "high",
"runs": 3
},
"pull_request": null,
"url": "https://sypnia.example.com/console/problems/pay-button-does-nothing",
"created_at": "2026-03-12T09:13:02Z"
}El análisis va recortado aquí; su forma completa está en la referencia de la API. occurrences es 5 y no 15: cada clic produjo tres fallas y una ocurrencia.
Qué cambió frente al sistema del que sale
| Allá | Aquí | Por qué |
|---|---|---|
| Grupos de errores por huella y entorno | Problemas por proyecto, entorno y huella | Varios proyectos |
| Se agrupaba una vez por hora | Cada 30 segundos, en la vía rápida | La promesa de 2 minutos |
| Las fallas del navegador y del servidor de una solicitud eran grupos separados | Un problema, por traza | Brief: una causa, una frase |
| Personas y sesiones por día, con arreglos limitados a 200 | Lo mismo por hora para la línea de tiempo, más problem_hits para un conteo exacto de toda la vida | «3 personas» es la frase del producto; debe ser exacta |
Un 4xx nunca era una falla del servidor; el navegador guardaba su código | Una llamada fallida es sin respuesta, 400, o 500 o más, también en el navegador | Para que una app con solo el SDK del navegador tenga problemas |
| Traducción de pilas dentro de la tarea de cada hora, 200 grupos por hora | Después de cada problema nuevo o que vuelve | Un problema nuevo necesita su archivo real dentro de los 2 minutos, para el agente |
| Reglas de fragmentos y digest de un solo framework dentro de la huella | Las mismas reglas, como una lista por plataforma | Cualquier framework, no uno |
hash64 sobre unidades UTF-16, en JavaScript | Lo mismo, bit por bit, en Rust | Los grupos existentes conservan sus huellas |
Sigue
- Qué le pasa a un problema después de nacer.
- Las mismas reglas, desde el lado de quien lee.
- Cómo subir los mapas que usa esta página.