Trazar y depurar en producción sin degradar el rendimiento

Llegas al final del nivel con cuatro herramientas en la mano: la ventana en vivo de tail, la historia persistente de Workers Logs, la telemetría a medida de Analytics Engine y las trazas legibles de los source maps. Falta la disciplina que las une. Depurar en producción en el edge no es adjuntar un debugger —eso ya vimos que es imposible— sino diseñar un sistema que se explique a sí mismo, y hacerlo con una restricción brutal: cada gramo de instrumentación cuesta CPU y latencia que tus usuarios pagan. La maestría de la observabilidad es esta paradoja resuelta: ver mucho, costar poco. Instrumentación tan barata que puedas dejarla siempre encendida, porque la telemetría que apagas para ganar rendimiento es exactamente la que te faltará durante el incidente.

Los tres pilares en la caja de Cloudflare

La observabilidad clásica se articula en tres pilares, y este nivel te ha dado una herramienta para cada uno. No son intercambiables: cada uno responde una pregunta que los otros responden mal.

Un incidente real se investiga saltando entre los tres: una métrica en Analytics Engine te dice que la latencia subió en una ruta, un log en Workers Logs te dice qué pasó en las invocaciones lentas, y la traza correlacionada te dice dónde —en qué salto, en qué servicio— se fue el tiempo. Ninguno solo basta.

console.log y excepciones: el rastro básico

El rastro más básico ya lo conoces: console.log, console.warn y console.error los captura tanto tail como Workers Logs. La disciplina, de la lección de Workers Logs, es registrar objetos estructurados y no frases, para poder consultarlos por campo. A eso se suma la gestión de excepciones, que en un Worker tiene reglas propias.

export default {
  async fetch(request, env, ctx) {
    const rayId = request.headers.get("cf-ray") ?? "sin-ray";
    try {
      return await manejar(request, env);
    } catch (err) {
      // Registra el error ENTERO: la plataforma remapea su traza con el source map
      console.error({ evento: "fallo", rayId, err });
      // Decide con intencion: propagar (outcome error) o degradar con gracia
      return new Response("Algo salio mal", { status: 500 });
    }
  },
};

Una excepción no capturada convierte la invocación en un outcome de tipo error, visible al instante con wrangler tail --status error. Capturarla te da la oportunidad de añadir contexto —el rayId, qué operación fallaba— antes de decidir si la propagas o devuelves una respuesta degradada. Registra siempre el objeto de error completo, no solo su mensaje: así la plataforma puede remapear su traza con el source map que subiste en la lección anterior.

Correlacionar: el cf-ray y el trace id

Un log suelto cuenta un fragmento; el valor aparece cuando puedes coser todos los fragmentos de una misma petición. Cloudflare asigna a cada petición un identificador único, el cf-ray, disponible en la cabecera del mismo nombre. Si lo incluyes en cada línea de log, puedes filtrar por él en Workers Logs y reconstruir la historia completa de esa invocación.

El salto a traza distribuida llega cuando tu Worker llama a otros —service bindings, subrequests, otro Worker—. Propaga un trace id por una cabecera y regístralo en cada eslabón: entonces una sola consulta por ese id te devuelve el recorrido entero a través de todos los servicios, que es lo más parecido a un depurador distribuido que el edge permite.

// Genera un trace id al entrar y propagalo a cada subrequest
const traceId = request.headers.get("x-trace-id") ?? crypto.randomUUID();
const upstream = await fetch(destino, {
  headers: { "x-trace-id": traceId },
});
console.log({ evento: "subrequest", traceId, estado: upstream.status });

flowchart TD
Q[incidente la latencia subio] --> M[metricas en Analytics Engine]
M -->|que ruta y cuando| L[logs en Workers Logs filtrados por cf-ray]
L -->|que paso dentro| T[traza por trace id entre servicios]
T -->|donde se fue el tiempo| R[causa raiz]
style M fill:#f9e2af,color:#11111b
style L fill:#89b4fa,color:#11111b
style T fill:#cba6f7,color:#11111b
style R fill:#a6e3a1,color:#11111b

Instrumentar sin degradar: el efecto observador

Aquí está la restricción que lo gobierna todo. Cada console.log consume tiempo de CPU, y hay límites por invocación —al número de líneas y a su tamaño— que un logging exuberante puede rozar. Peor aún: si escribes telemetría de forma bloqueante en el camino de la respuesta, esa latencia la sufre el usuario. Medir perturba lo medido, y en un Worker perturbar significa ir más lento.

El patrón que resuelve la tensión tiene tres movimientos:

export default {
  async fetch(request, env, ctx) {
    const inicio = Date.now();
    const respuesta = await manejar(request, env);

    // 1. La telemetria pesada va a Analytics Engine (no bloqueante, casi gratis)
    env.AE.writeDataPoint({
      indexes: [new URL(request.url).pathname],
      doubles: [Date.now() - inicio],
    });

    // 2. El trabajo diferido se hace con waitUntil: DESPUES de responder
    ctx.waitUntil(registrarAuditoria(request, respuesta));

    // 3. Devuelve ya; el usuario no espera a la instrumentacion
    return respuesta;
  },
};

Primero, deriva la telemetría de alto volumen a Analytics Engine, cuya escritura es fuego y olvido. Segundo, todo lo que no tenga que ocurrir antes de responder —enviar una auditoría, reenviar un log— envuélvelo en ctx.waitUntil(), que mantiene el isolate vivo para terminar ese trabajo después de que la respuesta ya viajó al usuario. Tercero, reserva Workers Logs para lo que de verdad quieres consultar, y controla su volumen con el head_sampling_rate. El resultado es instrumentación que el usuario no paga en latencia y que tu factura no paga en exceso.