Análisis de errores del servidor web

Un recuento de errores muestra que algo se rompió. El contexto estructurado (ruta, código de estado, versión e ID de solicitud) le ayuda a identificar qué falló y correlacionarlo con una implementación.

En el desarrollo web moderno, el monitoreo y el registro son aspectos críticos para mantener aplicaciones sólidas y confiables. Telemetry permite a los desarrolladores realizar un seguimiento de varios eventos y métricas del sistema, lo que puede ser crucial para depurar y mejorar la experiencia del usuario. En esta publicación, exploraremos cómo usar Telemetry API para detectar y registrar todos los errores en un servidor web Express.js. Aunque esta guía sólo cubre Express, las ideas son aplicables a todos los servidores web, desde Rails hasta Elixir, etc.

Configurar Telemetry

Antes de que podamos registrar datos, debemos configurar Telemetry. Para este ejemplo, usaremos Telemetry JavaScript SDK.

Primero, instale el Telemetry SDK en su proyecto:

npm install telemetry-sh

Luego, inicialice el cliente Telemetry en su aplicación con su clave API:

const telemetry = require("telemetry-sh");

telemetry.init(process.env.TELEMETRY_API_KEY);

Configura TELEMETRY_API_KEY en el entorno del servidor. No pongas la clave en el código del navegador ni la incluyas en un commit.

Crear una aplicación exprés

A continuación, configuremos una aplicación Express básica. Si aún no tienes Express instalado, puedes agregarlo a tu proyecto con el siguiente comando:

npm install express

Ahora, cree un servidor Express simple:

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

Agregar middleware de error estructurado

El controlador de errores pertenece después de todas las rutas. Capture categorías seguras y contexto operativo en lugar de cuerpos sin formato, credenciales, seguimientos de pila o mensajes de excepción que puedan contener valores privados.

// Add this after the real routes in your existing Express app.
app.use((err, req, res, next) => {
  if (res.headersSent) return next(err);
  const statusCode = Number(err.statusCode) || 500;
  const rawCode = typeof err.code === "string" ? err.code : "";
  const errorCode = /^[A-Z0-9_]{1,40}$/.test(rawCode)
    ? rawCode
    : "UNCLASSIFIED_ERROR";

  res.status(statusCode).json({ error: "Request failed" });

  void Promise.resolve()
    .then(() => telemetry.log("api_request_failed", {
      route_template: req.route?.path ?? "unmatched_route",
      method: req.method,
      status_code: statusCode,
      status: "error",
      error_type: err.constructor?.name ?? "Error",
      error_code: errorCode,
      request_id: res.locals.requestId ?? "missing",
      release: process.env.APP_RELEASE ?? "unknown",
    }))
    .catch(() => console.warn("Telemetry error event was not sent"));
});

Añade este controlador a la aplicación Express que atiende tus rutas reales. El ejemplo Hello World anterior no genera un evento de error. Ejecuta una solicitud real que falle y comprueba que su fila aparezca en api_request_failed. Si tu aplicación genera identificadores de solicitud de confianza, guarda uno en res.locals.requestId antes de este controlador. La respuesta se envía antes de entregar el evento a Telemetry; en entornos serverless, usa la tarea en segundo plano o el mecanismo de vaciado admitido por la plataforma.

Utilice plantillas de ruta como /api/projects/:id, no rutas sin formato que contengan identificadores de clientes. Mantenga el mismo esquema de eventos para las respuestas 4xx y 5xx manejadas cuando esas fallas sean importantes para el flujo de trabajo.

Consultar y visualizar errores.

Empiece por contar los fallos por ruta y versión; después conserve una tabla de eventos recientes para investigar:

SELECT
  route_template,
  release,
  status_code,
  error_code,
  COUNT(*) AS failures,
  MAX(timestamp_utc) AS last_seen_at
FROM api_request_failed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template, release, status_code, error_code
ORDER BY failures DESC, last_seen_at DESC;

Para obtener una tasa de error real, registre las solicitudes exitosas y fallidas en la misma tabla con un campo status o status_code compartido. Una tabla de sólo fallos puede clasificar los errores, pero no puede proporcionar el denominador.

Próximos pasos

Utilice Tasa de error API por receta de ruta para realizar una consulta segura con denominador, visualización de ejemplo, diseño de panel y guía de alertas. Combínelo con Percentiles de latencia API para que una vista de incidentes cubra tanto la corrección como la velocidad.