Análisis de trazas de pila

Domina el análisis de trazas de pila para identificar y corregir rápidamente errores de JavaScript en tu aplicación.

Entender las trazas de pila

Anatomía de una traza de pila

TypeError: Cannot read property 'email' of undefined
    at getUserEmail (user-service.js:45:12)    ← Ubicación del error
    at validateForm (form-handler.js:123:8)    ← Llamado desde aquí
    at HTMLFormElement.<anonymous> (form.js:67:5) ← Manejador de eventos
    at HTMLFormElement.dispatch (jquery.min.js:3:10456)
    at HTMLFormElement.v.handle (jquery.min.js:3:8765)

Componentes de un frame de pila

Cada línea contiene:

Componente	Ejemplo	Descripción
Función	getUserEmail	Nombre de función
Archivo	user-service.js	Archivo fuente
Línea	45	Número de línea
Columna	12	Posición de columna

Dirección de lectura

Lee las trazas de pila de arriba a abajo:

1. Frame superior: Donde ocurrió el error
2. Frames intermedios: Cadena de llamadas
3. Frames inferiores: Punto de entrada

Ver trazas de pila en Zenovay

El seguimiento de errores es una funcionalidad Pro. Una vez activado para un sitio web, los errores capturados se agrupan por huella digital y se muestran en la pestaña Errores del panel de control del sitio (/domains/{your-site}?tab=errors).

Para habilitarlo, abre la configuración del sitio web, ve a la sección Avanzado y activa Seguimiento de Errores en los indicadores de características.

La vista de detalles de error

Abre un grupo de errores desde la pestaña Errores para ver sus ocurrencias recientes. Para cada ocurrencia puedes revisar:

• El tipo y mensaje de error
• La URL de página donde sucedió
• Desglose de navegador, sistema operativo y dispositivo
• Los breadcrumbs (acciones del usuario antes) del error
• La traza de pila, mostrada como una lista expandible de frames

La traza de pila se colapsa de forma predeterminada. Expándela para ver cada frame como:

at getUserById (user-service.js:45:12)
at handleGetUser (api-handler.js:78:5)
at <anonymous> (router.js:23:3)

Las trazas largas se truncan a los primeros frames, con un indicador "más frames" para el resto. El nombre de función, archivo, línea y columna se muestran para cada frame para que puedas ir directo al código relevante en tu editor.

Source Maps

Los source maps permiten a Zenovay convertir trazas de pila de producción minificadas de vuelta a tu archivo fuente original, línea y columna.

Sin Source Maps

El código minificado produce trazas crípticas:

TypeError: a is not a function
    at e (main.abc123.js:1:34567)
    at t.handleClick (main.abc123.js:1:45678)
    at Object.onClick (main.abc123.js:1:56789)

Con Source Maps

El mismo error, legible:

TypeError: processPayment is not a function
    at handleCheckout (checkout.tsx:89:12)
    at CheckoutButton.handleClick (CheckoutButton.tsx:45:8)
    at onClick (form-events.ts:23:5)

Generar Source Maps

El primer paso es generar source maps durante tu build. Usa source maps ocultos en producción para que los archivos .map se creen pero nunca se referencien (o se sirvan) desde tu bundle público.

Webpack – generar source maps ocultos:

// webpack.config.js
module.exports = {
  devtool: 'hidden-source-map',
  // Los source maps se generan pero no se referencian en la salida
};

Vite – generar source maps ocultos:

// vite.config.js
export default {
  build: {
    sourcemap: 'hidden'
  }
};

Rollup – generar source maps ocultos:

// rollup.config.js
export default {
  output: {
    sourcemap: 'hidden'
  }
};

Etiqueta cada build con una versión de release (ver Correlación de versión abajo) para que los source maps y los errores se alineen con el mismo despliegue.

Analizar patrones comunes

Acceso a propiedades indefinidas

TypeError: Cannot read property 'name' of undefined
    at renderUser (user-card.js:23:15)

Análisis:

• El objeto esperado en la línea 23 es indefinido
• Verifica el flujo de datos a renderUser
• Probablemente falta una verificación nula

Patrón de corrección:

// Antes
const name = user.name;

// Después
const name = user?.name ?? 'Unknown';

Función no definida

ReferenceError: processPayment is not defined
    at handleSubmit (checkout.js:45:5)

Análisis:

• Función llamada pero no en alcance
• Verifica imports/exports
• Verifica el orden de carga del módulo

Errores de tipo

TypeError: users.map is not a function
    at renderUserList (list.js:12:20)

Análisis:

• users no es un array
• Verifica el formato de respuesta de la API
• Verifica las suposiciones de tipo de datos

Análisis avanzado

Trazas de pila asincrónicas

JavaScript moderno incluye contexto asincrónico:

Error: API request failed
    at fetchUser (api.js:34:11)
    at async loadUserData (user-loader.js:56:18)
    at async initApp (app.js:12:5)

Frames de origen cruzado

Scripts de terceros muestran información limitada:

Error: Script error.
    at <anonymous> (https://third-party.com/widget.js:1:1)

Solución: Añade encabezados CORS a scripts de terceros:

<script src="https://third-party.com/widget.js" crossorigin="anonymous"></script>

Código de terceros minificado

Para librerías sin source maps:

• Identifica la librería por patrón de URL
• Verifica la versión de la librería
• Busca problemas conocidos
• Considera alternativas

Flujo de depuración

Paso 1: Identificar la ubicación del error

1. Mira el frame superior de la pila
2. Anota archivo, línea, columna
3. Entiende qué hace el código

Paso 2: Rastrear la ruta de llamada

1. Sigue los frames hacia abajo en la pila
2. Identifica el flujo de datos
3. Encuentra de dónde provienen los datos malos

Paso 3: Verificar el contexto

1. Ve la frecuencia de ocurrencia del error a lo largo del tiempo en la pestaña Errores
2. Verifica navegadores/dispositivos afectados en el desglose
3. Lee los breadcrumbs que llevan al error

Paso 4: Reproducir

1. Usa relación de sesión (si está disponible en tu plan)
2. Verifica acciones del usuario antes del error
3. Prueba con el mismo navegador/condiciones

Paso 5: Corregir y verificar

1. Implementa la corrección
2. Despliega la nueva versión
3. Marca el grupo de errores como resuelto desde la vista de detalles del error
4. Monitorea regresiones

Gestionar el estado del error

Desde la vista de detalles del error puedes cambiar el estado de un grupo para mantener tu lista enfocada:

• No resuelto – necesita atención (predeterminado)
• Investigando – alguien está trabajando en ello
• Resuelto – corregido y verificado
• Ignorado – conocido e intencionalmente no tratado

Los cambios de estado requieren acceso de editor en el espacio de trabajo y se registran en el registro de auditoría del espacio de trabajo.

Correlación de versión

Cuando etiquetas tu seguimiento con una versión, cada error capturado registra la versión de la que provino, para que puedas decir qué despliegue introdujo un problema.

Etiquetar versiones

Establece un valor de versión en tu build para que el rastreador lo reporte con cada evento. El fragmento base se ve así:

<script
  defer
  data-tracking-code="YOUR_TRACKING_CODE"
  src="https://api.zenovay.com/z.js"
></script>

Empareja esto con los source maps correspondientes de tu build (etiquetados con la misma versión) para que las trazas de producción se simbolicen contra la versión correcta.

Mejores prácticas

Gestión de Source Maps

• Usa source maps ocultos en producción
• Mantén los source maps organizados por versión
• Etiqueta cada build con la versión de release que coincida con tu despliegue

Calidad de trazas de pila

• Usa nombres de función significativos
• Evita funciones anónimas
• Mantén las pilas de llamadas a profundidad razonable
• Añade contexto de error donde sea necesario

Eficiencia de depuración

• Comienza con los errores más impactados
• Usa estado (investigando, resuelto, ignorado) para enfocar la lista
• Documenta hallazgos
• Comparte con tu equipo

Solución de problemas

Source Maps faltantes

Verifica:

• Los source maps fueron generados para esta versión
• La versión coincide con lo que reporta el rastreador
• Los nombres de archivos se alinean con tus bundles desplegados

Trazas de pila incompletas

Causas:

• Código asincrónico no rastreado correctamente
• Errores de eval() o código dinámico
• Limitaciones del navegador

Mensajes "Script error"

Soluciones:

• Añade encabezados CORS
• Usa el atributo crossorigin
• Auto-aloja scripts de terceros

Próximos pasos

• Seguimiento de errores JavaScript
• Relación de sesión
• Monitoreo de rendimiento