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:

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

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.

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

telemetry.init(process.env.TELEMETRY_API_KEY);

const app = express();

app.get("/api/projects/:id", async (req, res) => {
  throw Object.assign(new Error("Synthetic failure"), {
    code: "PROJECT_LOOKUP_FAILED",
  });
});

app.use(async (err, req, res, next) => {
  const statusCode = Number(err.statusCode) || 500;

  await 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: err.code ?? "UNCLASSIFIED_ERROR",
    request_id: req.get("x-request-id") ?? "missing",
    release: process.env.APP_RELEASE ?? "unknown",
  });

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

app.listen(3000);

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.

Comience con la tasa de fallas por ruta y versión, luego mantenga 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.