Analytics Engine: telemetría a medida con SQL

Los logs responden a la pregunta “¿qué pasó en esta invocación concreta?”. Pero hay una pregunta distinta, que ningún log responde bien: “¿cuál es la forma agregada de todas mis invocaciones?” —cuántas por ruta, qué latencia media por país, cuántos pedidos por cliente y hora—. Para eso existe Workers Analytics Engine: un almacén de series temporales de alta cardinalidad al que tu Worker escribe eventos propios casi gratis, y que consultas después con SQL. Es la pieza que te convierte de consumidor de métricas ajenas en autor de tu propia telemetría: mides exactamente lo que tu negocio necesita medir, no lo que un panel prefabricado decidió mostrarte.

Logs y métricas son dos preguntas distintas

Un log es un registro puntual: cuenta la historia de una invocación y se lee de una en una. Una métrica es un agregado: no te importa un evento suelto, te importa la suma, la media, el percentil de millones de ellos. Podrías intentar reconstruir métricas releyendo logs, pero es caro, lento y su retención corta no llega. Analytics Engine invierte el enfoque: escribes datos pensados desde el principio para ser agregados, y los consultas con la herramienta natural de la agregación —SQL—.

Su superpoder es la alta cardinalidad. Los sistemas de métricas tradicionales colapsan cuando una etiqueta tiene demasiados valores distintos (un identificador de cliente, una URL única): cada combinación crea una serie nueva y el coste explota. Analytics Engine está diseñado para tragarse esa cardinalidad sin miedo, lo que te permite medir por cliente, por ruta o por cualquier dimensión granular que tu negocio necesite.

El binding y la escritura

Como todo recurso en el edge, Analytics Engine se accede por un binding declarado en wrangler.jsonc, no por credenciales:

{
  "analytics_engine_datasets": [
    { "binding": "AE", "dataset": "metricas_app" }
  ]
}

Desde el Worker, escribir un evento es una sola llamada sobre env.AE:

export default {
  async fetch(request, env, ctx) {
    const inicio = Date.now();
    const url = new URL(request.url);
    const pais = request.cf?.country ?? "XX";

    // ... la lógica del Worker ...

    env.AE.writeDataPoint({
      indexes: [url.pathname],               // clave de muestreo (1 como maximo)
      blobs: [pais, request.method],         // dimensiones: hasta 20 cadenas
      doubles: [Date.now() - inicio],        // metricas: hasta 20 numeros
    });

    return new Response("ok");
  },
};

La anatomía de un data point

Un data point tiene tres compartimentos, y elegir bien qué va en cada uno es el arte de esta herramienta:

El orden importa y es posicional: el primer blob será blob1 en SQL, el primer double será double1, el único indexes será index1. No hay nombres de columna; hay posiciones. Documenta en tu código qué mide cada posición, porque en la consulta no habrá etiquetas que te lo recuerden.

Consultar con SQL y el _sample_interval

Se consulta por una API HTTP a la que envías SQL como cuerpo de la petición, autenticada con un token de API:

curl "https://api.cloudflare.com/client/v4/accounts/TU_ACCOUNT_ID/analytics_engine/sql" \
  -H "Authorization: Bearer TU_TOKEN" \
  -d "SELECT blob1 AS pais, SUM(_sample_interval) AS peticiones
      FROM metricas_app
      WHERE timestamp > NOW() - INTERVAL '1' DAY
      GROUP BY pais ORDER BY peticiones DESC"

Aquí aparece el concepto que no puedes ignorar: el muestreo adaptativo. Cuando el volumen es alto, Analytics Engine no guarda todos los eventos, sino una muestra, y anota en cada fila cuántos eventos reales representa a través de la columna _sample_interval. Si una fila tiene un _sample_interval de 100, significa “esta fila vale por 100 eventos que ocurrieron de verdad”.

La consecuencia es una regla de oro: nunca cuentes filas, cuenta a través del intervalo de muestreo. Un COUNT(*) te dice cuántas filas guardó Cloudflare, no cuántos eventos ocurrieron. La verdad se obtiene ponderando:

-- MAL: cuenta filas muestreadas, no la realidad
SELECT blob1 AS ruta, COUNT(*) FROM metricas_app GROUP BY ruta;

-- BIEN: estima el total real ponderando por el intervalo
SELECT blob1 AS ruta,
       SUM(_sample_interval)              AS peticiones_reales,
       SUM(_sample_interval * double1)    AS suma_duracion_real
FROM metricas_app
WHERE timestamp > NOW() - INTERVAL '1' HOUR
GROUP BY ruta ORDER BY peticiones_reales DESC;

flowchart LR
W[Worker writeDataPoint] --> AE[dataset de Analytics Engine]
AE -->|muestreo adaptativo| S[filas con sample_interval]
S --> API[SQL API por HTTP]
API --> Q[SUM sample_interval estima el total real]
Q --> G[panel o Grafana]
style W fill:#89b4fa,color:#11111b
style S fill:#f9e2af,color:#11111b
style Q fill:#a6e3a1,color:#11111b