BIGboss248/nextjs-wordpress

Habilidad de Observabilidad OpenTelemetry para Next.js (nextjs-otel)

Un flujo de trabajo modular y listo para producción para configurar, probar y verificar el trazado de OpenTelemetry en aplicaciones Next.js App Router, estandarizando un único interruptor de apagado, protegiendo contra errores de inicialización de @vercel/otel y automatizando la verificación de trazas.

---

Resumen del Flujo de Trabajo

flowchart TD
    A["1. Evaluación del Proyecto<br/>(App Router y package.json)"] --> B["2. Instalación de Dependencias<br/>(@vercel/otel y @opentelemetry/api)"]
    B --> C["3. Desplegar instrumentation.ts<br/>(registerOTel + onRequestError)"]
    C --> D["4. Configurar Entorno<br/>(.env.example y .env.local)"]
    D --> E["5. Verificación y Pruebas<br/>(Recolector Simulado e Interruptor de Apagado)"]

---

Manual de Ejecución Paso a Paso

Sigue esta lista de verificación secuencialmente para configurar y verificar la observabilidad de OpenTelemetry:

1. Descubrimiento del Proyecto e Inspección de Dependencias

• Inspeccionar la Estructura del Proyecto: Confirmar la versión de Next.js App Router en package.json y el gestor de paquetes (pnpm, bun, npm).
• Localizar la Raíz de Instrumentación: Verificar si el proyecto usa instrumentation.ts en la raíz o src/instrumentation.ts.
• Revisar Estándares Arquitectónicos: Consultar architectural-standards.md para la disciplina del interruptor de apagado único y los límites de tiempo de ejecución.

2. Instalación de Dependencias

• Instalar Paquetes de Telemetría Core:

  pnpm add @vercel/otel @opentelemetry/api
  

3. Desplegar instrumentation.ts

• Crear Archivo de Instrumentación: Desplegar instrumentation.ts.template en la raíz o en src/.
• Aplicar Salvaguarda de Veracidad: Asegurarse de que register() elimine process.env.OTEL_SDK_DISABLED cuando no sea estrictamente "true" para evitar errores de evaluación booleana de @vercel/otel.
• Conectar Seguimiento de Errores: Asegurarse de que onRequestError() capture next.error.digest, la ruta y los metadatos HTTP en los spans activos.

4. Configurar Variables de Entorno

• Actualizar Plantillas de Entorno: Inyectar la configuración de OpenTelemetry en .env.example y .env.local usando env.otel.template.
• Establecer Nombre del Servicio y Protocolo: Configurar OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT y OTEL_EXPORTER_OTLP_PROTOCOL=http/json.

5. Verificación y Pruebas

• Iniciar Recolector OTLP Simulado: Iniciar el recolector de prueba en el puerto 4318 según verification-and-testing.md:

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

• Verificar Trazas Activas (OTEL_SDK_DISABLED=false): Disparar solicitudes de prueba (curl http://localhost:3000/) y verificar lotes POST /v1/traces con HTTP 200 OK.
• Verificar Interruptor de Apagado (OTEL_SDK_DISABLED=true): Confirmar que el servidor de Next.js registra [OTel] Instrumentation hook skipped y exporta 0 trazas.
• Generar Informe de Verificación: Generar un informe de resumen en Markdown.

---

Casos Límite y Errores Conocidos de IA

[!ADVERTENCIA]

• El Error de Veracidad de Cadenas de @vercel/otel: @vercel/otel evalúa !!process.env.OTEL_SDK_DISABLED. En JavaScript, Boolean("false") es true. Sin eliminar process.env.OTEL_SDK_DISABLED cuando no sea 'true', establecer OTEL_SDK_DISABLED=false deshabilita el trazado silenciosamente.
• Banderas Personalizadas Secundarias: Nunca introducir OTEL_ENABLED junto con OTEL_SDK_DISABLED. Estandarizar estrictamente en OTEL_SDK_DISABLED.
• Violaciones de Límites de Tiempo de Ejecución: Nunca importar instrumentation.ts ni los SDK de OpenTelemetry del servidor en Componentes Cliente ("use client").
• Comandos Encadenados: Nunca encadenar comandos (&&, ||, ;). Ejecutar todos los comandos de configuración y prueba individualmente.

---

Esquema del Resumen de Salida

Al completar la configuración o verificación de OpenTelemetry, generar un informe estructurado:

# Informe de Verificación de OpenTelemetry

## Resumen de Estado

- **Estado de OTel**: Activo / Deshabilitado
- **Nombre del Servicio**: <nombre_del_servicio_configurado>
- **Endpoint de Destino**: <endpoint_configurado>
- **Protocolo del Exportador**: http/json | http/protobuf

## Resultados de la Verificación

| Verificación                | Esperado                      | Actual              | Estado |
| :-------------------------- | :---------------------------- | :------------------ | :----- |
| Hook de Inicialización      | Registrado                    | Registrado          | PASÓ   |
| Despacho de Trazas (Activo) | POST /v1/traces (200 OK)      | X lotes recibidos   | PASÓ   |
| Interruptor de Apagado (Deshabilitado) | Omitido, 0 trazas | Omitido, 0 trazas   | PASÓ   |
| Verificación de Tipos       | 0 errores                     | 0 errores           | PASÓ   |

---

Guías de Referencia y Plantillas

• Referencia de Estándares Arquitectónicos — Disciplina del interruptor de apagado, mecánica del error de veracidad y contexto de error.
• Manual de Verificación y Pruebas — Instrucciones del arnés de pruebas, disparadores curl y verificación del interruptor de apagado.
• Plantilla de Instrumentación — instrumentation.ts completo con manejo de errores.
• Plantilla de Configuración de Entorno — Claves completas de configuración de .env.
• Script del Recolector Simulado — Arnés ligero de recolector HTTP OTLP en Node.js.