Cómo configurar el monitoreo de Datadog para una aplicación de Webflow Cloud

Webflow Cloud ejecuta tu aplicación en el entorno de ejecución de Cloudflare, pero Webflow es el propietario de la cuenta de Cloudflare. No tienes un host donde instalar nada ni una consola de infraestructura donde habilitar nada. Lo que sí tienes es código capaz de realizar peticiones salientes, y eso es suficiente.

Esta guía detalla el proceso completo para instrumentar tu aplicación de Webflow Cloud con Datadog. Aprenderás a definir una estrategia de monitorización que funcione dentro de las limitaciones de la plataforma y a enviar métricas personalizadas directamente desde tus Route Handlers sin bloquear las peticiones.

¿Qué necesitas para configurar la monitorización de Datadog en Webflow Cloud?

Necesitas una cuenta de Datadog, una clave de API, el sitio correcto para esa cuenta y una aplicación de Webflow Cloud que puedas editar. La gente suele equivocarse con el sitio.

Aquí tienes la lista completa antes de empezar:

• Una cuenta de Datadog con permiso para crear claves de API en la configuración de la organización
• Tu sitio de Datadog, que es la región donde reside tu cuenta y determina cada URL a la que llamarás

• Una aplicación de Webflow Cloud en Next.js 15 o superior, con Node.js 22 o posterior instalado localmente

• Una idea clara de los dos o tres números que realmente te indicarían que algo va mal

Ese último punto no es relleno. Datadog factura las métricas personalizadas según combinaciones únicas de nombres y etiquetas, por lo que medirlo todo tiene un coste. La disciplina de elegir qué medir es parte de la configuración, no un ajuste que se pueda hacer más tarde.

Una vez creada la cuenta, todo depende de acertar con el sitio, porque si eliges el incorrecto, el fallo no genera ningún tipo de aviso.

5 pasos para configurar la monitorización de Datadog para una aplicación de Webflow Cloud

La implementación incluye una clave de API, una función que envía una métrica, una forma de enviarla sin retrasar la respuesta, una decisión sobre las etiquetas y el monitor que hace que todo sea útil.

El orden importa porque el cuarto paso es mucho más difícil de cambiar una vez que las métricas empiezan a fluir bajo nombres para los que ya has creado paneles de control.

1. Crea una clave de API y confirma tu sitio de Datadog

En Datadog, abre la configuración de la organización, ve a las claves de API y crea una. Los valores de la clave de API permanecen visibles allí para que puedas consultarlos. No confundas esto con una clave de aplicación, que es una credencial distinta y que las organizaciones más nuevas solo muestran una vez al crearla.

Luego busca tu sitio, que es más importante que la clave. Datadog gestiona nueve sitios independientes, divididos por región y régimen de cumplimiento, y la documentación indica claramente que no se pueden compartir datos entre ellos.

Cada sitio tiene su propio nombre de host de API, por lo que una cuenta en el sitio de la UE que publique en el endpoint de EE. UU. no está enviando datos al panel equivocado; está enviando datos a una organización que no te incluye.

Datadog también enumera el sitio en la parte superior de Mis preferencias, aunque su documentación describe esto específicamente para organizaciones con un dominio personalizado, así que no consideres un espacio vacío ahí como una respuesta válida.

Almacena ambos valores como variables de entorno en el entorno de Webflow Cloud en lugar de en el repositorio. Webflow Cloud pone las variables de entorno a disposición tanto de la compilación como de la aplicación desplegada en tiempo de ejecución, y oculta los valores secretos de los registros de compilación.

Terminarás este paso con una clave y una cadena de sitio que has leído en lugar de haber asumido.

2. Escribe la función que envía una métrica

Las métricas se dirigen al endpoint de series en el host de la API de tu sitio. Toda la integración es una sola función, y vale la pena escribirla tú mismo en lugar de recurrir a una biblioteca que espera un tiempo de ejecución que no tienes.

<><fragmento de introducción>:

// lib/datadog.ts
type Point = {
  metric: string
  value: number
  tags: string[]
  // 3 = gauge (a measurement, averaged), 1 = count (summed).
  // A duration is a gauge. Sending it as a count graphs two
  // 200ms requests as 400.
  type?: 1 | 3
}

export async function sendMetric({ metric, value, tags, type = 3 }: Point) {
  // Seconds, not milliseconds. Datadog rejects points more than
  // 10 minutes ahead or an hour behind, and Date.now() lands
  // roughly 55,000 years in the future.
  const now = Math.floor(Date.now() / 1000)

  // Read the key here rather than at module scope: the adapter
  // populates process.env on the first request, not at startup.
  const DD_API_KEY = process.env.DD_API_KEY

  const site = process.env.DD_SITE ?? 'datadoghq.com'

  const res = await fetch(`https://api.${site}/api/v2/series`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'DD-API-KEY': DD_API_KEY!,
    },
    body: JSON.stringify({
      series: [
        {
          metric,
          type,
          points: [{ timestamp: now, value }],
          tags,
        },
      ],
    }),
  })

  // A bad key returns 403 with a body, not a thrown error.
  if (!res.ok) {
    console.error('datadog rejected the metric', res.status, await res.text())
  }
}

Tres detalles ahí se ganan su lugar. La marca de tiempo está en segundos en lugar de milisegundos, que es la razón más común por la que una primera métrica nunca aparece.

El tipo predeterminado es gauge, porque la mayor parte de lo que medirás es un nivel en lugar de un recuento, y una duración enviada como recuento se suma en lugar de promediarse. Además, la rama de error registra en lugar de lanzar una excepción, porque una métrica rechazada nunca debería tumbar la solicitud que estaba midiendo.

Si envías un recuento, la API de Datadog también requiere un interval en segundos, así que añade ese campo en lugar de dejar la tasa ambigua.

Ten en cuenta también que Datadog no limita la tasa de envío de métricas o registros, por lo que la restricción sobre cuánto envías es la facturación, no la limitación de velocidad. Sigue existiendo un límite de carga útil de 500 kilobytes por solicitud, lo cual solo importa si empiezas a procesar por lotes.

Terminarás este paso con una función que puedes llamar desde cualquier parte de la aplicación.

3. Envíala sin ralentizar tu propia respuesta

Llamar a esa función con await dentro de un Route Handler añade un viaje de ida y vuelta a Datadog a cada solicitud que esperan tus usuarios. En un endpoint de pago, eso es un coste real pagado por clientes reales para registrar un número que nadie lee en tiempo real.

Usa el waitUntil del contexto de Cloudflare en su lugar, que mantiene la solicitud activa el tiempo suficiente para terminar el envío después de que la respuesta haya salido:

// app/api/checkout/route.ts
import { getCloudflareContext } from '@opennextjs/cloudflare'
import { sendMetric } from '@/lib/datadog'

export async function POST(request: Request) {
  const started = Date.now()
  const result = await processCheckout(request)

  const { ctx } = getCloudflareContext()

  // Hand the send to waitUntil so the metric leaves after the
  // response does. Awaiting it here would add Datadog's round
  // trip to every checkout your customers wait through.
  ctx.waitUntil(
    sendMetric({
      metric: 'app.checkout.duration',
      value: Date.now() - started,
      tags: [
        `env:${process.env.WEBFLOW_ENV ?? 'production'}`,
        `status:${result.ok ? 'ok' : 'failed'}`,
      ],
    }),
  )

  return Response.json(result)
}

Esto importa más en Webflow Cloud que en otros lugares, porque la plataforma solo permite seis solicitudes salientes simultáneas por invocación y aplica un tiempo de espera de solicitud de veinte segundos. Una llamada de monitoreo bloqueante compite con las llamadas que tu función realmente necesita.

Después de este paso, puedes acceder al endpoint y ver cómo aparece la métrica en el Metrics Explorer.

4. Elige las etiquetas con cuidado, porque las etiquetas son la factura

Detente antes de añadir etiquetas, porque aquí es donde las configuraciones de monitoreo se vuelven costosas sin que te des cuenta. Datadog define una métrica personalizada como una combinación única del nombre de la métrica y sus valores de etiqueta, lo que significa que el recuento por el que se te factura es multiplicativo en lugar de aditivo.

Una métrica etiquetada con entorno y estado tiene un puñado de combinaciones. La misma métrica, etiquetada adicionalmente con ID de usuario, tiene tantas combinaciones como usuarios tengas. Los ID de solicitud, los ID de sesión, las rutas URL completas que contienen ID y los mensajes de error sin procesar se comportan de la misma manera, y cada uno de ellos convierte una métrica en miles.

La regla que funciona es etiquetar con cosas por las que agruparías, no por las que buscarías. El entorno, el nombre de la ruta, la clase de estado y la región son agrupaciones. Un ID de usuario es una búsqueda y pertenece a una línea de registro donde no te cuesta nada, no en una etiqueta de métrica donde se multiplica.

Si quieres detalles por usuario, envíalo como un registro y mantén la métrica general.

Terminas este paso con una lista de etiquetas que podrías justificar en una factura.

5. Crea el monitor que realmente te avisa

Que una métrica llegue a Datadog no es monitorizar. Nada está bajo control hasta que recibes un aviso cuando la cifra se mueve.

En Datadog, abre Monitors, luego New Monitor, elige Metric y selecciona la métrica que acabas de enviar. Establece un umbral que realmente justifique despertarte y envía las notificaciones a un lugar donde las leas, no a uno que tengas silenciado.

Presta especial atención a la configuración de "no data". Una aplicación que ha dejado de responder por completo no envía métricas, por lo que un monitor de umbral que vigila un recuento alto de errores no verá nada y se quedará callado.

Esa es precisamente la caída que más te interesa conocer, y es la que un umbral básico ignora. Configura el monitor para que alerte tanto por falta de datos como por datos erróneos.

Termina este paso con una alerta que hayas activado a propósito al menos una vez; es la única forma de saber que la ruta de notificación funciona.

¿Qué hace que la monitorización de Datadog falle en Webflow Cloud?

La monitorización falla de una forma especialmente molesta: lo que debería avisarte de que algo va mal, falla a su vez y no le comunica su propio error a nadie.

Cuatro causas explican casi todo, y la primera es la que más tiempo consume porque no genera ningún error en ninguna parte.

Las métricas nunca aparecen en Datadog

Causa: Normalmente, el sitio de Datadog es incorrecto. Esto falla de dos formas distintas y conviene saber cuál tienes. Una clave de un sitio enviada a otro host es rechazada directamente con un error 403, que verás en el registro del paso 2.

Una clave válida para el host al que enviaste los datos, pero no para el sitio que estás viendo en el navegador, funciona silenciosamente y coloca tus datos en una organización que no estás consultando.

Solución: Registra el estado de la respuesta de la llamada de entrada una vez. Un 403 significa que la clave y el host no coinciden. Un 202 significa que Datadog aceptó la carga, así que los datos existen en algún lugar; la siguiente pregunta es si estás mirando el sitio al que los enviaste.

Comprueba que el nombre de host en el que has iniciado sesión coincida con el DD_SITE valor con el que se desplegó la aplicación, ya que los sitios son totalmente independientes y no pueden compartir datos.

La métrica se acepta pero no aparece en ningún gráfico

Causa: La marca de tiempo está en milisegundos en lugar de segundos. Date.now() devuelve milisegundos, lo que sitúa el punto unos 55.000 años en el futuro. Datadog documenta una ventana de aceptación estricta de no más de diez minutos en el futuro o una hora en el pasado, así que el punto no se guarda en un lugar inaccesible; simplemente se descarta.

Solución: Divide por 1000 y redondea hacia abajo, como hace el asistente del paso 2. No intentes buscar los puntos perdidos después ampliando la ventana del gráfico; nunca se llegaron a escribir, así que lo único que debes comprobar es que los nuevos puntos aparezcan una vez que la conversión sea correcta.

Vale la pena detectar esto con una prueba deliberada en lugar de por observación. Envía una sola métrica manualmente, búscala en un gráfico y solo entonces intégrala en un Route Handler. Un error de marca de tiempo detectado en el primer punto cuesta un minuto; detectado tras una semana de tráfico, significa una semana de datos que no puedes graficar.

Las respuestas se vuelven más lentas tras añadir la monitorización

Causa: La llamada de recepción se espera dentro de la solicitud en lugar de enviarse a waitUntil. Ahora, cada usuario espera a Datadog antes de ver su respuesta y, en un día lento para Datadog, esperan a que se agote el tiempo de espera.

Solución: Mueva el envío a ctx.waitUntil como se indicó anteriormente, para que la respuesta salga primero y la métrica la siga. Recuerde también que Webflow Cloud limita las solicitudes salientes simultáneas a seis por invocación, por lo que un controlador que ya se distribuye a varios servicios y luego añade una llamada de monitoreo bloqueante puede terminar haciendo cola frente a su propia instrumentación.

El fallo que vale la pena anticipar es cuando Datadog mismo está lento. Una llamada en espera vincula su tiempo de respuesta a la disponibilidad de un tercero, lo que significa que una incidencia en su proveedor de monitoreo se convierte en una incidencia en su sitio. Pasar el envío a waitUntil elimina ese acoplamiento por completo.

La factura de Datadog crece más rápido que el tráfico

Causa: Etiquetas de alta cardinalidad. Una métrica etiquetada con algo único por solicitud o por usuario no es una métrica personalizada; es una por cada valor distinto, y el recuento aumenta silenciosamente porque el código no parece diferente.

Solución: Revise la página de detalles de uso, que enumera las principales métricas personalizadas de la cuenta, y encuentre la métrica cuyo nombre reconoce pero cuyo volumen no. Luego, elimine la etiqueta problemática y mueva ese detalle a una línea de registro, donde la misma información no le cuesta nada por valor distinto.

Haga esto pronto. Una vez que los paneles y monitores se basan en una etiqueta, eliminarla significa reconstruir ambos, y la presión en ese momento es seguir pagando en lugar de deshacerlo. El momento más barato para corregir la cardinalidad es antes de que alguien dependa de la forma de los datos.

Qué monitorear a continuación en su aplicación de Webflow Cloud

Una vez que una métrica y una alerta funcionan de principio a fin, las adiciones más útiles suelen ser errores y registros, no más números. El seguimiento de errores responde a qué se rompió y dónde, algo que una métrica nunca hará.

Si ya utiliza Sentry para excepciones y desea Datadog junto a él para los registros, nuestra guía de Sentry y Datadog cubre esa combinación directamente. Evita duplicar lo que cada herramienta hace mejor.

Para la parte del lado del navegador, que no necesita código de servidor, la integración de Webflow y Datadog cubre el monitoreo de usuarios reales y las pruebas sintéticas en sus páginas publicadas.

Para los límites de la plataforma que definen todo esto, incluidos los límites de solicitudes salientes, los tiempos de espera y el almacén de clave-valor, los límites de Webflow Cloud son la página que debe leer antes de diseñar cualquier cosa que se ejecute en cada solicitud.