Cómo configurar instrumentación con OpenTelemetry

La observabilidad es crucial para comprender y optimizar el comportamiento y rendimiento de tu aplicación Next.js.

A medida que las aplicaciones se vuelven más complejas, resulta cada vez más difícil identificar y diagnosticar problemas que puedan surgir. Al aprovechar herramientas de observabilidad, como registros y métricas, los desarrolladores pueden obtener información sobre el comportamiento de su aplicación e identificar áreas para optimización. Con la observabilidad, los desarrolladores pueden abordar problemas de manera proactiva antes de que se conviertan en problemas mayores y ofrecer una mejor experiencia de usuario. Por lo tanto, se recomienda encarecidamente utilizar la observabilidad en tus aplicaciones Next.js para mejorar el rendimiento, optimizar recursos y mejorar la experiencia de usuario.

Recomendamos usar OpenTelemetry para instrumentar tus aplicaciones. Es una forma independiente de plataforma para instrumentar aplicaciones que te permite cambiar tu proveedor de observabilidad sin modificar tu código. Consulta la documentación oficial de OpenTelemetry para obtener más información sobre OpenTelemetry y cómo funciona.

Esta documentación utiliza términos como Span (Intervalo), Trace (Traza) o Exporter (Exportador) a lo largo de este documento, todos los cuales puedes encontrar en el Manual de Observabilidad de OpenTelemetry.

Next.js admite la instrumentación con OpenTelemetry de forma nativa, lo que significa que ya hemos instrumentado Next.js en sí mismo.

Primeros pasos

OpenTelemetry es extensible, pero configurarlo correctamente puede ser bastante detallado. Por eso preparamos un paquete @vercel/otel que te ayuda a comenzar rápidamente.

Usando `@vercel/otel`

Para comenzar, instala los siguientes paquetes:

Terminal

npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation

A continuación, crea un archivo personalizado instrumentation.ts (o .js) en el directorio raíz del proyecto (o dentro de la carpeta src si estás usando una):

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel({ serviceName: 'next-app' })
}

Consulta la documentación de @vercel/otel para ver opciones de configuración adicionales.

Nota importante:

El archivo instrumentation debe estar en la raíz de tu proyecto y no dentro de los directorios app o pages. Si estás usando la carpeta src, coloca el archivo dentro de src junto a pages y app.

Si usas la opción de configuración pageExtensions para agregar un sufijo, también necesitarás actualizar el nombre del archivo instrumentation para que coincida.

Hemos creado un ejemplo básico with-opentelemetry que puedes utilizar.

Configuración manual de OpenTelemetry

El paquete @vercel/otel proporciona muchas opciones de configuración y debería cubrir la mayoría de los casos de uso comunes. Pero si no se adapta a tus necesidades, puedes configurar OpenTelemetry manualmente.

Primero necesitas instalar los paquetes de OpenTelemetry:

Terminal

npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

Ahora puedes inicializar NodeSDK en tu instrumentation.ts. A diferencia de @vercel/otel, NodeSDK no es compatible con el entorno de ejecución edge, por lo que debes asegurarte de importarlos solo cuando process.env.NEXT_RUNTIME === 'nodejs'. Recomendamos crear un nuevo archivo instrumentation.node.ts que importes condicionalmente solo cuando uses node:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node.ts')
  }
}

Hacer esto es equivalente a usar @vercel/otel, pero es posible modificar y extender algunas características que no están expuestas por @vercel/otel. Si necesitas compatibilidad con el entorno de ejecución edge, tendrás que usar @vercel/otel.

Probando tu instrumentación

Necesitas un recolector OpenTelemetry con un backend compatible para probar las trazas de OpenTelemetry localmente. Recomendamos usar nuestro entorno de desarrollo OpenTelemetry.

Si todo funciona correctamente, deberías poder ver el span raíz del servidor etiquetado como GET /ruta/solicitada. Todos los demás spans de esa traza particular estarán anidados debajo de él.

Next.js rastrea más spans de los que se emiten por defecto. Para ver más spans, debes establecer NEXT_OTEL_VERBOSE=1.

Despliegue

Usando OpenTelemetry Collector

Cuando te despliegues con OpenTelemetry Collector, puedes usar @vercel/otel. Funcionará tanto en Vercel como en autoalojamiento.

Desplegando en Vercel

Nos aseguramos de que OpenTelemetry funcione de forma nativa en Vercel.

Sigue la documentación de Vercel para conectar tu proyecto a un proveedor de observabilidad.

Autoalojamiento

Desplegar en otras plataformas también es sencillo. Necesitarás iniciar tu propio OpenTelemetry Collector para recibir y procesar los datos de telemetría de tu aplicación Next.js.

Para hacer esto, sigue la guía de inicio de OpenTelemetry Collector, que te guiará a través de la configuración del recolector y cómo configurarlo para recibir datos de tu aplicación Next.js.

Una vez que tengas tu recolector en funcionamiento, puedes desplegar tu aplicación Next.js en la plataforma de tu elección siguiendo sus respectivas guías de despliegue.

Exportadores personalizados

OpenTelemetry Collector no es necesario. Puedes usar un exportador OpenTelemetry personalizado con @vercel/otel o configuración manual de OpenTelemetry.

Spans personalizados

Puedes agregar un span personalizado con las APIs de OpenTelemetry.

Terminal

npm install @opentelemetry/api

El siguiente ejemplo demuestra una función que obtiene estrellas de GitHub y agrega un span personalizado fetchGithubStars para rastrear el resultado de la solicitud fetch:

import { trace } from '@opentelemetry/api'

export async function fetchGithubStars() {
  return await trace
    .getTracer('nextjs-example')
    .startActiveSpan('fetchGithubStars', async (span) => {
      try {
        return await getValue()
      } finally {
        span.end()
      }
    })
}

La función register se ejecutará antes de que tu código se ejecute en un nuevo entorno. Puedes comenzar a crear nuevos spans, y deberían agregarse correctamente a la traza exportada.

Spans predeterminados en Next.js

Next.js instrumenta automáticamente varios spans para proporcionar información útil sobre el rendimiento de tu aplicación.

Los atributos en los spans siguen las convenciones semánticas de OpenTelemetry. También agregamos algunos atributos personalizados bajo el espacio de nombres next:

next.span_name - duplica el nombre del span
next.span_type - cada tipo de span tiene un identificador único
next.route - El patrón de ruta de la solicitud (ej. /[param]/user).
next.rsc (verdadero/falso) - Indica si la solicitud es una solicitud RSC, como prefetch.
next.page
- Este es un valor interno utilizado por el enrutador de aplicaciones.
- Puedes considerarlo como una ruta a un archivo especial (como page.ts, layout.ts, loading.ts y otros)
- Puede usarse como identificador único solo cuando se combina con next.route porque /layout puede usarse para identificar tanto /(groupA)/layout.ts como /(groupB)/layout.ts

`[http.method] [next.route]`

next.span_type: BaseServer.handleRequest

Este span representa el span raíz para cada solicitud entrante a tu aplicación Next.js. Rastrea el método HTTP, ruta, objetivo y código de estado de la solicitud.

Atributos:

Atributos HTTP comunes
- http.method
- http.status_code
Atributos HTTP del servidor
- http.route
- http.target
next.span_name
next.span_type
next.route

`render route (app) [next.route]`

next.span_type: AppRender.getBodyResult.

Este span representa el proceso de renderizar una ruta en el enrutador de aplicaciones.

Atributos:

next.span_name
next.span_type
next.route

`fetch [http.method] [http.url]`

next.span_type: AppRender.fetch

Este span representa la solicitud fetch ejecutada en tu código.

Atributos:

Atributos HTTP comunes
- http.method
Atributos HTTP del cliente
- http.url
- net.peer.name
- net.peer.port (solo si se especifica)
next.span_name
next.span_type

Este span se puede desactivar estableciendo NEXT_OTEL_FETCH_DISABLED=1 en tu entorno. Esto es útil cuando quieres usar una biblioteca de instrumentación fetch personalizada.