Cómo leer los logs de tu aplicación (y encontrar el error)

Cuando una aplicación deja de responder, el log es el primer lugar donde mirar. Es el diario del proceso: todo lo que imprime tu código y todo lo que el runtime reporta termina ahí. Saber leerlo te ahorra horas de prueba y error.

El problema casi nunca es la falta de información, sino el exceso. Un log de producción tiene cientos de líneas, y el error útil es una sola. Para llegar a ella, sigue un método fijo, siempre en el mismo orden.

¿De dónde salen las líneas del log?#

Todo proceso tiene dos flujos de salida. stdout recibe la salida normal: console.log en Node.js, print en Python. stderr recibe los errores: console.error y el mensaje que imprime el runtime cuando una excepción no se maneja.

En una terminal o en un panel de hosting, los dos aparecen mezclados, en el orden en que llegaron. Eso ayuda, porque ves lo que hacía la aplicación justo antes de fallar.

En Node.js, una excepción no capturada imprime el stack trace en stderr y termina el proceso con código 1, según la documentación de process. Una promesa rechazada sin manejo (unhandledRejection) se lanza, por defecto, como excepción no capturada. Por eso un await sin try/catch puede tumbar el bot entero.

¿Cuál es el método para encontrar el error?#

Estos son los pasos:

1. Ve al final del log. Lo último que pasó es el síntoma actual.
2. Sube hasta la primera línea de error. Busca Error, Exception, Traceback, FATAL o ECONNREFUSED. Las advertencias (warn) rara vez son la causa.
3. Lee el mensaje completo. Te dice el tipo de error y, casi siempre, qué faltó: un módulo, una variable, un puerto.
4. Encuentra la primera línea de tu código en el stack trace. Las líneas de node_modules o de bibliotecas muestran por dónde pasó el error. La línea con la ruta de tu archivo muestra dónde lo provocó tu código.
5. Revisa lo que pasó antes. Un fallo de conexión con la base de datos puede haber empezado 30 líneas por encima del error final.

Si la aplicación se reinicia una y otra vez, el log guarda cada intento, uno detrás de otro. Compara el último con el anterior: el error que se repite es el que importa.

¿Cómo se lee un stack trace de Node.js?#

Este es un ejemplo de excepción no capturada:

/home/app/index.js:12
  const nombre = usuario.perfil.nombre;
                                ^

TypeError: Cannot read properties of undefined (reading 'nombre')
    at obtenerNombre (/home/app/index.js:12:33)
    at procesarMensaje (/home/app/handlers/mensaje.js:8:5)

Node.js v24.0.0

Léelo de arriba hacia abajo:

• La línea con ^ señala el punto exacto del código.
• TypeError: ... es el tipo y el mensaje. Aquí, usuario.perfil es undefined.
• Las líneas at son la pila de llamadas, de la más reciente a la más antigua. La primera línea con la ruta de tu proyecto (/home/app/index.js:12:33) te da archivo, línea y columna.
• La última línea muestra la versión de Node.js, útil para confirmar el runtime en uso.

El stack trace de Node muestra dónde se creó el error y se extiende hasta el inicio de la ejecución síncrona, o hasta el límite de frames de Error.stackTraceLimit (consulta la documentación de errores). En código asíncrono, algunas llamadas intermedias pueden no aparecer.

¿Cómo se lee un traceback de Python?#

Python usa el orden inverso: la llamada más reciente queda al final.

Traceback (most recent call last):
  File "/home/app/main.py", line 20, in <module>
    iniciar()
  File "/home/app/main.py", line 14, in iniciar
    token = os.environ["TOKEN"]
  File "<frozen os>", line 714, in __getitem__
KeyError: 'TOKEN'

Empieza por la última línea: KeyError: 'TOKEN' dice que la variable de entorno TOKEN no existe. Luego sube para encontrar la línea de tu código que lo causó (main.py, línea 14). El encabezado Traceback (most recent call last) avisa que la llamada más reciente está abajo, como muestra la documentación del módulo traceback.

Cuando hay dos excepciones encadenadas, Python imprime During handling of the above exception, another exception occurred: entre los bloques. La causa original está en el primer bloque, y el error que llegó al final está en el último.

¿Qué errores aparecen más al arrancar una aplicación?#

Si la aplicación se cae y vuelve sin parar, el log muestra el mismo error en cada arranque. Es un ciclo de reinicios causado por un error fijo, y el reinicio automático solo lo repite. Lee la guía sobre PM2 y reinicio automático para entender este comportamiento.

¿Cómo escribir logs que de verdad ayuden?#

Un buen log responde "qué, cuándo y con qué dato" sin exponer secretos.

• Usa niveles. info para hitos normales, warn para lo que merece atención, error para fallos. Así puedes filtrar.
• Incluye contexto. fallo al guardar usuario 4821: timeout ayuda más que error.
• Registra el objeto de error completo, no solo el mensaje. Sin el stack trace pierdes el lugar del fallo.
• Nunca imprimas contraseñas, tokens ni datos personales. Un log lo lee más gente de la que imaginas.
• Escribe en stdout y stderr. Así no dependes de una ruta de archivo ni de la rotación.

Un ejemplo mínimo en Node.js:

process.on("unhandledRejection", (motivo) => {
  console.error("unhandledRejection:", motivo);
});

async function guardar(id) {
  try {
    await db.guardar(id);
    console.log(`usuario ${id} guardado`);
  } catch (error) {
    console.error(`fallo al guardar usuario ${id}`, error);
  }
}

En Python, el módulo logging de la biblioteca estándar hace lo mismo, y logging.exception("mensaje") ya incluye el traceback.

Cómo hacerlo en Square Cloud#

En Square Cloud, los logs de tu aplicación aparecen en tiempo real en el panel, la CLI, la extensión de VS Code y la app móvil. Aplicas el mismo método y sigues un deploy o un error sin abrir una terminal en ningún servidor.

Las aplicaciones corren en contenedores aislados. El reinicio automático es opcional y viene activado cuando haces el deploy desde el panel: levanta la aplicación cuando el proceso termina con error. Los logs de antes de un reinicio siguen visibles, así que, después de un reinicio inesperado, sube en el log para encontrar el error que lo causó. Quedarse sin memoria es distinto: la aplicación se detiene y solo vuelve cuando aumentas su RAM y la inicias de nuevo.

Cuando cambias una variable de entorno, el cambio se aplica en el siguiente reinicio, sin rebuild: reinicia y vuelve a leer el log para confirmarlo. Cubic, el agente de IA del panel, también lee logs para diagnosticar fallos, siempre que tú se lo pidas. Las métricas de CPU, RAM y red se registran cada 5 minutos y se guardan 24 horas, lo que te ayuda a cruzar un error de memoria con el consumo real.

Consulta las funciones de logs y métricas en las funciones de la plataforma.