Workers Logs: retención persistente y búsqueda

wrangler tail te da una ventana en vivo, pero una ventana solo muestra el presente: en cuanto la cierras, lo que pasó se pierde. La operación real necesita lo contrario —poder preguntar “¿qué ocurrió a las tres de la madrugada, cuando yo dormía?”—. Workers Logs es esa capa: captura automáticamente los console.log, las excepciones y los metadatos de cada invocación, los retiene durante unos días y te deja buscarlos desde el panel de Cloudflare con la potencia de un motor de consultas. El giro conceptual es grande: dejas de mirar un flujo que pasa y empiezas a interrogar un conjunto de datos que se queda.

De la ventana efímera al almacén persistente

Workers Logs recoge, sin que escribas una línea extra de código, todo lo que tu Worker ya emite: cada console.log, console.warn y console.error, cada excepción no capturada, y los metadatos de la invocación (resultado, estado HTTP, duración de CPU, nombre del script). Lo guarda en un almacén indexado y lo expone en el panel, bajo la sección de observabilidad, con un constructor de consultas: filtras por rango temporal, por campos, por texto, y abres cualquier invocación para ver su rastro completo.

La diferencia con tail no es de grado sino de naturaleza. tail es un flujo que solo existe mientras lo miras; Workers Logs es un registro que persiste aunque nadie mire. Uno responde “¿qué está pasando ahora?”; el otro, “¿qué pasó entonces?”. En un incidente los usas juntos: tail para la reacción en caliente, Workers Logs para la investigación posterior y para el patrón que solo se ve mirando horas de datos.

Activar la observabilidad en wrangler.jsonc

La observabilidad no se enciende en un menú del panel, sino en tu manifiesto —lo que la hace versionable, revisable y reproducible junto al resto de la configuración—. El bloque vive en wrangler.jsonc:

{
  "name": "mi-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

enabled: true activa la captura y el almacenamiento de logs para ese Worker. head_sampling_rate es un número entre 0 y 1 que decide qué fracción de invocaciones se registra: un 1 lo guarda todo, un 0.1 guarda una de cada diez. En cuanto redespliegas con wrangler deploy, la configuración toma efecto y los logs empiezan a aparecer en el panel.

Buscar como si fuera una tabla

Aquí está el verdadero poder, y depende de cómo escribas tus logs. Si registras texto plano, solo puedes buscar por subcadena. Pero si registras objetos estructurados, Workers Logs indexa cada campo y te deja filtrar por él en el constructor de consultas, igual que un WHERE sobre columnas.

// Log plano: solo buscable por texto
console.log("pedido " + orderId + " fallo con estado " + status);

// Log estructurado: cada campo se vuelve un filtro en el panel
console.log({
  evento: "pedido_fallido",
  orderId,
  status,
  tenant: "acme",
  duracionMs: Date.now() - inicio,
});

Con la segunda forma, el panel te permite consultas del tipo “muéstrame las invocaciones donde evento es pedido_fallido y tenant es acme”, combinables con los metadatos que Cloudflare añade por su cuenta bajo un espacio reservado (el resultado de la invocación, el estado HTTP, la duración). Tus logs dejan de ser prosa que relees y se convierten en un conjunto de datos que interrogas.

flowchart LR
R[invocacion del Worker] --> H{head sampling elige esta?}
H -->|no| X[no se registra]
H -->|si| C[captura console y excepciones]
C --> S[campos estructurados indexados]
S --> D[almacen persistente unos dias]
D --> Q[constructor de consultas en el panel]
Q --> F[filtra por campo tenant evento status]
style C fill:#89b4fa,color:#11111b
style S fill:#94e2d5,color:#11111b
style D fill:#cba6f7,color:#11111b
style X fill:#f38ba8,color:#11111b

Reenviar a sistemas externos: Tail Workers

Cuando necesitas más de lo que el panel ofrece —retención de meses, correlación con logs de otros servicios, alertas en tu herramienta de guardia— Cloudflare deja que un Tail Worker consuma los eventos de otro Worker y haga con ellos lo que quieras: filtrarlos, transformarlos y reenviarlos a un destino externo. Se declara con tail_consumers en el manifiesto del Worker productor, y el consumidor recibe cada lote de eventos en un handler tail. Es la vía canónica para llevar la observabilidad de Cloudflare a un pipeline propio sin renunciar al modelo del edge.