Next.js

SDK de Next.js para ClickStack - La pila de observabilidad de ClickHouse

ClickStack puede ingestar trazas nativas de OpenTelemetry desde tus funciones sin servidor de Next.js en Next 13.2+.

Esta guía integra:

• Logs de consola
• Trazas

Si buscas session replay/monitorización del lado del navegador, te conviene instalar la integración de navegador en su lugar.

​

Instalación

​

Habilitar el hook de instrumentación (obligatorio para v15 y versiones anteriores)

Para empezar, deberá habilitar el hook de instrumentación de Next.js configurando experimental.instrumentationHook = true; en su archivo next.config.js.

Ejemplo:

const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
  // Ignorar advertencias de paquetes OTel 
  // https://github.com/open-telemetry/opentelemetry-js/issues/4173#issuecomment-1822938936
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack },
  ) => {
    if (isServer) {
      config.ignoreWarnings = [{ module: /opentelemetry/ }];
    }
    return config;
  },
};

module.exports = nextConfig;

​

Instalar el SDK de OpenTelemetry para ClickHouse

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

​

Crear archivos de instrumentación

Crea un archivo llamado instrumentation.ts (o .js) en la raíz de tu proyecto de Next.js con el contenido siguiente:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { init } = await import('@hyperdx/node-opentelemetry');
    init({
      apiKey: '<YOUR_INGESTION_API_KEY>', // opcionalmente configurable mediante la variable de entorno `HYPERDX_API_KEY`
      service: '<MY_SERVICE_NAME>', // opcionalmente configurable mediante la variable de entorno `OTEL_SERVICE_NAME`
      additionalInstrumentations: [], // opcional, valor predeterminado: []
    });
  }
}

Esto permitirá que Next.js importe la instrumentación de OpenTelemetry para cualquier invocación de una función sin servidor.

​

Configurar variables de entorno

Si estás enviando trazas directamente a ClickStack mediante OpenTelemetry, tendrás que iniciar tu servidor de Next.js con las siguientes variables de entorno para enviar los spans al OTel collector:

Managed ClickStack

copy

OTEL_SERVICE_NAME=<MY_SERVICE_NAME> \
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4318
npm run dev

ClickStack Open Source

copy

HYPERDX_API_KEY=<YOUR_INGESTION_API_KEY> \
OTEL_SERVICE_NAME=<MY_SERVICE_NAME> \
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4318
npm run dev

Si haces el despliegue en Vercel, asegúrate de que todas las variables de entorno anteriores estén configuradas para tu despliegue.