Observabilidade OpenTelemetry para Next.js

Habilidade de Observabilidade OpenTelemetry para Next.js (nextjs-otel)

Um fluxo de trabalho modular e pronto para produção para configurar, testar e verificar o tracing OpenTelemetry em aplicações Next.js App Router, padronizando o uso de uma única chave de interrupção, protegendo contra bugs de inicialização do @vercel/otel e automatizando a verificação de traces.

---

Visão Geral do Fluxo de Trabalho

flowchart TD
    A["1. Avaliação do Projeto<br/>(App Router & package.json)"] --> B["2. Instalar Dependências<br/>(@vercel/otel & @opentelemetry/api)"]
    B --> C["3. Implantar instrumentation.ts<br/>(registerOTel + onRequestError)"]
    C --> D["4. Configurar Ambiente<br/>(.env.example & .env.local)"]
    D --> E["5. Verificar & Harness de Teste<br/>(Coletor Simulado & Chave de Interrupção)"]

---

Manual de Execução Passo a Passo

Siga esta lista de verificação sequencialmente para configurar e verificar a observabilidade OpenTelemetry:

1. Descoberta do Projeto e Inspeção de Dependências

• Inspecionar Estrutura do Projeto: Confirmar a versão do Next.js App Router no package.json e o gerenciador de pacotes (pnpm, bun, npm).
• Localizar Raiz da Instrumentação: Verificar se o projeto usa o arquivo raiz instrumentation.ts ou src/instrumentation.ts.
• Revisar Padrões Arquiteturais: Consultar architectural-standards.md para disciplina de chave de interrupção única e limites de runtime.

2. Instalação de Dependências

• Instalar Pacotes Principais de Telemetria:

  pnpm add @vercel/otel @opentelemetry/api
  

3. Implantar instrumentation.ts

• Criar Arquivo de Instrumentação: Implantar instrumentation.ts.template na raiz ou em src/.
• Aplicar Salvaguarda de Veracidade: Garantir que register() remova process.env.OTEL_SDK_DISABLED quando não for estritamente "true" para evitar bugs de avaliação booleana do @vercel/otel.
• Vincular Rastreamento de Erros: Garantir que onRequestError() capture next.error.digest, o caminho da rota e metadados HTTP nos spans ativos.

4. Configurar Variáveis de Ambiente

• Atualizar Templates de Ambiente: Injetar configuração OpenTelemetry em .env.example e .env.local usando env.otel.template.
• Definir Nome do Serviço e Protocolo: Configurar OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT e OTEL_EXPORTER_OTLP_PROTOCOL=http/json.

5. Verificação e Teste

• Iniciar Coletor OTLP Simulado: Iniciar o coletor de teste na porta 4318 conforme verification-and-testing.md:

  node .agents/skills/nextjs-otel/scripts/mock_collector.js
  

• Verificar Traces Ativos (OTEL_SDK_DISABLED=false): Disparar requisições de teste (curl http://localhost:3000/) e verificar lotes POST /v1/traces com HTTP 200 OK.
• Verificar Chave de Interrupção (OTEL_SDK_DISABLED=true): Confirmar que o servidor Next.js registra [OTel] Instrumentation hook skipped e exporta 0 traces.
• Gerar Relatório de Verificação: Produzir relatório resumido em Markdown.

---

Casos Extremos e Armadilhas Conhecidas de IA

[!WARNING]

• O Bug de Veracidade de String do @vercel/otel: O @vercel/otel avalia !!process.env.OTEL_SDK_DISABLED. Em JavaScript, Boolean("false") é true. Sem remover process.env.OTEL_SDK_DISABLED quando não for 'true', definir OTEL_SDK_DISABLED=false desativa o tracing silenciosamente.
• Flags Personalizadas Secundárias: Nunca introduzir OTEL_ENABLED junto com OTEL_SDK_DISABLED. Padronizar estritamente em OTEL_SDK_DISABLED.
• Violações de Limites de Runtime: Nunca importar instrumentation.ts ou SDKs OpenTelemetry do servidor em Componentes Cliente ("use client").
• Comandos Encadeados: Nunca encadear comandos (&&, ||, ;). Executar todos os comandos de configuração e teste individualmente.

---

Esquema de Resumo de Saída

Após concluir a configuração ou verificação do OpenTelemetry, gerar um relatório estruturado:

# Relatório de Verificação OpenTelemetry

## Resumo de Status

- **Status OTel**: Ativo / Desativado
- **Nome do Serviço**: <nome_do_serviço_configurado>
- **Endpoint de Destino**: <endpoint_configurado>
- **Protocolo do Exportador**: http/json | http/protobuf

## Resultados da Verificação

| Verificação              | Esperado                    | Atual              | Status |
| :----------------------- | :-------------------------- | :----------------- | :----- |
| Hook de Inicialização    | Registrado                  | Registrado         | PASS   |
| Envio de Traces (Ativo)  | POST /v1/traces (200 OK)    | X lotes recebidos  | PASS   |
| Chave de Interrupção (Desativado) | Ignorado, 0 traces | Ignorado, 0 traces | PASS   |
| Verificação de Tipos     | 0 erros                     | 0 erros            | PASS   |

---

Guias de Referência e Modelos

• Referência de Padrões Arquiteturais — Disciplina de chave de interrupção, mecânica do bug de veracidade e contexto de erro.
• Manual de Verificação e Teste — Instruções do harness de teste, comandos curl e verificação da chave de interrupção.
• Modelo de Instrumentação — instrumentation.ts completo com tratamento de erros.
• Modelo de Configuração de Ambiente — Chaves de configuração .env completas.
• Script do Coletor Simulado — Harness leve de coletor OTLP HTTP em Node.js.