Observar una ruta existente de Next.js

Usa esta receta en una aplicación Next.js App Router existente, con una versión actual que incluya los parches y un despliegue Node.js compatible. La API after es estable desde Next.js 15.1; esta versión mínima de la API no recomienda instalar una versión antigua sin parches. Observa si el manejador devuelve una Response o lanza una excepción; no mide la entrega al navegador, el final de una respuesta transmitida ni una tarea de negocio en segundo plano.

Antes de cambiar la ruta

Elige una ruta que controles y una operación autorizada que puedas ejecutar sin riesgo. Conserva su autenticación, validación y lógica. Define TELEMETRY_API_KEY solo en el servidor, nunca con el prefijo NEXT_PUBLIC_. La clave anónima de la página principal permite enviar y consultar; una clave de cuenta necesita permisos read-and-write para la verificación. Usa una clave de solo ingesta para una aplicación que solo envía.

Añadir el ayudante del servidor

Guárdalo como lib/with-telemetry.js. Usa una plantilla de ruta fija sin identificadores de clientes. El ID generado identifica esta invocación, no una persona ni una tarea lógica. No se envían URL, cuerpos, cookies, cabeceras ni mensajes de error.

import { after } from 'next/server';
import { randomUUID } from 'node:crypto';

function warnTelemetry(message) {
  try {
    console.warn(message);
  } catch {
    // Diagnostic failure must not change the application outcome.
  }
}

export function withTelemetry(handler, routeTemplate) {
  return async function observedHandler(request, context) {
    const started = performance.now();
    const invocationId = randomUUID();
    let outcome = 'threw';
    let statusCode = null;
    try {
      const response = await handler(request, context);
      outcome = 'returned_response';
      statusCode = response.status;
      return response;
    } finally {
      const event = {
        invocation_id: invocationId,
        route_template: routeTemplate,
        method: request.method,
        handler_outcome: outcome,
        status_code: statusCode,
        latency_ms: performance.now() - started,
        environment: process.env.NODE_ENV || 'development',
      };
      try {
        after(async () => {
          const key = process.env.TELEMETRY_API_KEY;
          if (!key) {
            warnTelemetry('Telemetry key missing; event not sent');
            return;
          }
          try {
            const response = await fetch('https://api.telemetry.sh/log', {
              method: 'POST',
              headers: {
                Authorization: `Bearer ${key}`,
                'Content-Type': 'application/json',
              },
              cache: 'no-store',
              signal: AbortSignal.timeout(2000),
              body: JSON.stringify({ table: 'nextjs_route_observed', data: event }),
            });
            if (!response.ok) warnTelemetry('Telemetry event send rejected');
          } catch {
            warnTelemetry('Telemetry event send failed');
          }
        });
      } catch {
        warnTelemetry('Telemetry background scheduling failed');
      }
    }
  };
}

Envolver el manejador existente

Renombra la función GET exportada existente como existingGET sin cambiar su cuerpo. Exporta después el envoltorio siguiente. Adapta el método y la plantilla fija a la ruta real; no crees un manejador ficticio que siempre devuelva éxito para completar la configuración.

import { withTelemetry } from "@/lib/with-telemetry";

export const GET = withTelemetry(existingGET, "/api/reports/:id");

Verificar una invocación real

Ejecuta la operación autorizada en tu aplicación y consulta la tabla en Telemetry. Contrasta ruta, método, hora, resultado y estado con la operación observada. La aceptación HTTP no basta. Una prueba aislada, una ruta de demostración o una ejecución de control del agente no es una integración de cliente; reserva telemetry_quickstart para envíos ficticios.

SELECT invocation_id, route_template, method, handler_outcome,
       status_code, latency_ms, environment, timestamp_utc
FROM nextjs_route_observed
WHERE timestamp_utc >= now() - INTERVAL '15 minutes'
ORDER BY timestamp_utc DESC
LIMIT 20;

Lo que no garantiza

Next.js after programa el envío tras finalizar la respuesta. No es una cola duradera: los límites de ejecución, cierres, tiempos de espera y fallos de red pueden perder eventos. El envío tiene un límite de dos segundos y avisos fijos sin datos privados; no promete reintentos ni deduplicación. Conserva los registros existentes y usa una entrega duradera para auditorías obligatorias.

latency_ms termina cuando el manejador devuelve o lanza, antes del envío. returned_response puede incluir respuestas 4xx o 5xx. threw puede incluir redirecciones y control de flujo del framework; no implica automáticamente un fallo del servidor. Las claves ausentes y los fallos de telemetría no deben sustituir la respuesta o excepción original. Comprueba el ayudante en tu entorno antes del despliegue.

Referencia del framework y siguientes pasos

La referencia de Next.js after documenta versiones y despliegues compatibles. La exportación estática no es compatible; los adaptadores requieren soporte explícito. Se comprobaron la conservación de respuestas, las excepciones y los fallos de envío en una aplicación App Router de desarrollo aislada con Next.js 16.3.8, interceptando el envío de eventos y desactivando la red externa. Esto no verifica la ingesta real en Telemetry ni tu servidor de producción. Continúa con la verificación de ingesta y la guía del SDK JavaScript para ampliar la instrumentación.

Usa esta documentación con tu agente de programación