nextjs-otel

Compétence d'Observabilité Next.js OpenTelemetry (nextjs-otel)

Un flux de travail modulaire et prêt pour la production pour configurer, tester et vérifier le tracing OpenTelemetry dans les applications Next.js App Router, en standardisant un unique kill switch, en se protégeant contre les bugs d'initialisation de @vercel/otel, et en automatisant la vérification des traces.

---

Aperçu du Flux de Travail

flowchart TD
    A["1. Évaluation du Projet<br/>(App Router & package.json)"] --> B["2. Installation des Dépendances<br/>(@vercel/otel & @opentelemetry/api)"]
    B --> C["3. Déploiement de instrumentation.ts<br/>(registerOTel + onRequestError)"]
    C --> D["4. Configuration de l'Environnement<br/>(.env.example & .env.local)"]
    D --> E["5. Vérification & Test<br/>(Collecteur Simulé & Kill Switch)"]

---

Guide d'Exécution Pas à Pas

Suivez cette liste de vérification de manière séquentielle pour configurer et vérifier l'observabilité OpenTelemetry :

1. Découverte du Projet & Inspection des Dépendances

• Inspecter la Structure du Projet : Confirmer la version de Next.js App Router dans package.json et le gestionnaire de paquets (pnpm, bun, npm).
• Localiser la Racine d'Instrumentation : Vérifier si le projet utilise instrumentation.ts à la racine ou dans src/instrumentation.ts.
• Revoir les Standards Architecturaux : Consulter architectural-standards.md pour la discipline du kill switch unique et les limites d'exécution.

2. Installation des Dépendances

• Installer les Paquets de Télémétrie de Base :

  pnpm add @vercel/otel @opentelemetry/api
  

3. Déploiement de instrumentation.ts

• Créer le Fichier d'Instrumentation : Déployer instrumentation.ts.template à la racine ou dans src/.
• Appliquer la Sauvegarde de Véracité : S'assurer que register() supprime process.env.OTEL_SDK_DISABLED lorsqu'il n'est pas strictement "true" pour éviter les bugs d'évaluation booléenne de @vercel/otel.
• Connecter le Suivi des Erreurs : S'assurer que onRequestError() capture next.error.digest, le chemin de la route et les métadonnées HTTP sur les spans actifs.

4. Configuration des Variables d'Environnement

• Mettre à Jour les Modèles d'Environnement : Injecter la configuration OpenTelemetry dans .env.example et .env.local en utilisant env.otel.template.
• Définir le Nom du Service et le Protocole : Configurer OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, et OTEL_EXPORTER_OTLP_PROTOCOL=http/json.

5. Vérification & Tests

• Lancer le Collecteur OTLP Simulé : Démarrer le collecteur de test sur le port 4318 conformément à verification-and-testing.md :

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

• Vérifier les Traces Actives (OTEL_SDK_DISABLED=false) : Déclencher des requêtes de test (curl http://localhost:3000/) et vérifier les lots POST /v1/traces avec HTTP 200 OK.
• Vérifier le Kill Switch (OTEL_SDK_DISABLED=true) : Confirmer que le serveur Next.js enregistre [OTel] Instrumentation hook skipped et exporte 0 traces.
• Générer le Rapport de Vérification : Produire un rapport récapitulatif en Markdown.

---

Cas Limites & Pièges IA Connus

[!WARNING]

• Le Bug de Véracité de Chaîne de @vercel/otel : @vercel/otel évalue !!process.env.OTEL_SDK_DISABLED. En JavaScript, Boolean("false") est true. Sans supprimer process.env.OTEL_SDK_DISABLED lorsqu'il n'est pas 'true', définir OTEL_SDK_DISABLED=false désactive le tracing silencieusement.
• Drapeaux Personnalisés Secondaires : Ne jamais introduire OTEL_ENABLED en parallèle de OTEL_SDK_DISABLED. Standardiser strictement sur OTEL_SDK_DISABLED.
• Violations des Limites d'Exécution : Ne jamais importer instrumentation.ts ou les SDK OpenTelemetry serveur dans les Composants Client ("use client").
• Commandes Chaînées : Ne jamais chaîner les commandes (&&, ||, ;). Exécuter toutes les commandes de configuration et de test individuellement.

---

Schéma du Résumé de Sortie

Après avoir terminé la configuration ou la vérification OpenTelemetry, générer un rapport structuré :

# Rapport de Vérification OpenTelemetry

## Résumé d'État

- **État OTel** : Actif / Désactivé
- **Nom du Service** : <nom_service_configuré>
- **Point de Terminaison Cible** : <point_terminaison_configuré>
- **Protocole d'Exportation** : http/json | http/protobuf

## Résultats de Vérification

| Vérification            | Attendu                     | Réel               | Statut |
| :---------------------- | :-------------------------- | :----------------- | :----- |
| Hook d'Initialisation   | Enregistré                  | Enregistré         | PASS   |
| Envoi de Trace (Actif)  | POST /v1/traces (200 OK)    | X lots reçus       | PASS   |
| Kill Switch (Désactivé) | Ignoré, 0 traces            | Ignoré, 0 traces   | PASS   |
| Vérification de Type    | 0 erreurs                   | 0 erreurs          | PASS   |

---

Guides de Référence & Modèles

• Référence des Standards Architecturaux — Discipline du kill switch, mécanique du bug de véracité et contexte d'erreur.
• Guide de Vérification et de Test — Instructions pour le banc de test, déclencheurs curl et vérification du kill switch.
• Modèle d'Instrumentation — instrumentation.ts complet avec gestion des erreurs.
• Modèle de Configuration d'Environnement — Clés de configuration .env complètes.
• Script du Collecteur Simulé — Banc de collecteur HTTP OTLP Node.js léger.