Instrumentation

Core Idea

Use o arquivo instrumentation.ts|js para rodar código uma única vez no startup do servidor Next.js, tipicamente para integrar ferramentas de monitoramento/logging (ex.: OpenTelemetry) antes que a aplicação passe a atender requisições.

Key Concepts

• instrumentation.ts|js: arquivo na raiz do projeto (ou dentro de src/ se usado); convenção reservada para setup de observabilidade.
• register(): função exportada, chamada uma única vez quando uma nova instância do servidor Next.js é iniciada; deve completar antes do servidor aceitar requisições.
• NEXT_RUNTIME: variável de ambiente ('nodejs' ou 'edge') para importar condicionalmente código específico de runtime dentro de register(), já que register é chamado em todos os ambientes.

Code Examples

// instrumentation.ts
import { registerOTel } from '@vercel/otel'

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

• O que demonstra: integração mínima com OpenTelemetry via @vercel/otel.

// instrumentation.ts
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 dentro de register(), evitando carregar código incompatível com Edge.

Anti-patterns

• Importar arquivos com side effects no topo do arquivo instrumentation.ts: prefira import() dinâmico dentro de register(), para colocar todos os side effects num único lugar e evitar consequências não intencionais de import global.
• Colocar instrumentation.ts dentro de app/ ou pages/: deve ficar na raiz do projeto (ou em src/ junto de pages/app), nunca dentro dessas pastas.
• Ignorar pageExtensions: se o projeto usa a config pageExtensions para adicionar sufixo, o nome do arquivo instrumentation também precisa ser atualizado para casar.

Key Takeaways

1. register() roda uma única vez por instância de servidor e bloqueia o servidor até completar.
2. NEXT_RUNTIME é a forma correta de segregar código Node.js de código Edge dentro de register().
3. Prefira import() dinâmico dentro da função a import estático no topo do arquivo, para colocar side effects num só lugar.

Connects To

• instrumentation.js (API reference): referência completa da convenção do arquivo.
• How Revalidation Works (ch043): observabilidade de cache/revalidação em produção frequentemente se apoia no setup feito aqui.