Instrumentation

Core Idea

instrumentation.ts|js na raiz do projeto exporta uma função register() chamada uma única vez quando uma nova instância do servidor Next.js sobe, ideal pra plugar monitoramento/logging (ex.: OpenTelemetry) antes do servidor aceitar requests.

Key Concepts

• Convenção: arquivo instrumentation.ts|js na raiz (ou dentro de src/ se usado), nunca dentro de app ou pages.
• register(): roda uma vez por instância de servidor, e precisa completar antes do servidor ficar pronto pra requests.
• Import com side effect dentro de register: recomenda-se await import(...) dentro da função, não no topo do arquivo, pra colocalizar side effects.
• NEXT_RUNTIME: env var ('nodejs' ou 'edge') usada pra importar condicionalmente código específico de runtime, já que register roda em todos os ambientes.
• pageExtensions: se customizado, o nome do arquivo instrumentation precisa acompanhar a extensão configurada.

Code Examples

import { registerOTel } from '@vercel/otel'

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

• O que demonstra: setup mínimo de OpenTelemetry via @vercel/otel.

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

• O que demonstra: import condicional por runtime pra evitar carregar código incompatível.

Anti-patterns

• Import de side effect no topo do arquivo: espalha efeitos colaterais fora do ponto de controle; prefira await import(...) dentro de register().
• Não considerar NEXT_RUNTIME: código Node.js-only importado sem guarda quebra em runtime Edge.

Key Takeaways

1. register() é o único hook garantido a rodar antes do servidor aceitar tráfego.
2. Sempre colocar instrumentation.ts na raiz (ou src/), nunca dentro de pages/app.
3. Usar NEXT_RUNTIME pra separar código Node.js de Edge dentro do mesmo register.

Connects To

• ch315 OpenTelemetry: uso mais aprofundado do mesmo mecanismo de instrumentação.
• ch294 Analytics: instrumentation-client.js|ts é o equivalente client-side desse conceito.