nextjs-otel

Next.js OpenTelemetry Observability Skill (nextjs-otel)

Ein modularer, produktionsreifer Workflow zur Konfiguration, zum Testen und zur Verifizierung von OpenTelemetry-Tracing in Next.js App Router-Anwendungen. Er standardisiert einen einzigen Kill-Switch, schützt vor Initialisierungsfehlern von @vercel/otel und automatisiert die Trace-Verifikation.

---

Workflow-Übersicht

flowchart TD
    A["1. Projektbewertung<br/>(App Router & package.json)"] --> B["2. Abhängigkeiten installieren<br/>(@vercel/otel & @opentelemetry/api)"]
    B --> C["3. instrumentation.ts bereitstellen<br/>(registerOTel + onRequestError)"]
    C --> D["4. Umgebung konfigurieren<br/>(.env.example & .env.local)"]
    D --> E["5. Verifizierung & Test-Harness<br/>(Mock Collector & Kill-Switch)"]

---

Schritt-für-Schritt-Ausführungs-Runbook

Befolgen Sie diese Checkliste sequentiell, um OpenTelemetry-Observability zu konfigurieren und zu verifizieren:

1. Projektentdeckung & Abhängigkeitsprüfung

• Projektstruktur prüfen: Bestätigen Sie die Next.js App Router-Version in package.json und den Paketmanager (pnpm, bun, npm).
• Instrumentierungs-Wurzelverzeichnis finden: Prüfen Sie, ob das Projekt instrumentation.ts im Root oder in src/instrumentation.ts verwendet.
• Architekturstandards prüfen: Konsultieren Sie architectural-standards.md für die Disziplin des einzigen Kill-Switches und Laufzeitgrenzen.

2. Abhängigkeiten installieren

• Kern-Telemetriepakete installieren:

  pnpm add @vercel/otel @opentelemetry/api
  

3. instrumentation.ts bereitstellen

• Instrumentierungsdatei erstellen: Stellen Sie instrumentation.ts.template im Root oder in src/ bereit.
• Wahrheits-Absicherung anwenden: Stellen Sie sicher, dass register() process.env.OTEL_SDK_DISABLED löscht, wenn es nicht strikt "true" ist, um boolesche Auswertungsfehler von @vercel/otel zu vermeiden.
• Fehlerverfolgung einrichten: Stellen Sie sicher, dass onRequestError() next.error.digest, den Routenpfad und HTTP-Metadaten in aktiven Spans erfasst.

4. Umgebungsvariablen konfigurieren

• Umgebungsvorlagen aktualisieren: Fügen Sie die OpenTelemetry-Konfiguration in .env.example und .env.local ein, indem Sie env.otel.template verwenden.
• Service-Namen und Protokoll festlegen: Konfigurieren Sie OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT und OTEL_EXPORTER_OTLP_PROTOCOL=http/json.

5. Verifizierung & Test

• Mock OTLP Collector starten: Starten Sie den Test-Collector auf Port 4318 gemäß verification-and-testing.md:

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

• Aktive Traces verifizieren (OTEL_SDK_DISABLED=false): Lösen Sie Testanforderungen aus (curl http://localhost:3000/) und verifizieren Sie POST /v1/traces-Batches mit HTTP 200 OK.
• Kill-Switch verifizieren (OTEL_SDK_DISABLED=true): Bestätigen Sie, dass der Next.js-Server [OTel] Instrumentation hook skipped protokolliert und 0 Traces exportiert.
• Verifizierungsbericht ausgeben: Generieren Sie eine Zusammenfassung im Markdown-Format.

---

Randfälle & bekannte KI-Fallstricke

[!WARNING]

• Der @vercel/otel String-Wahrheits-Bug: @vercel/otel wertet !!process.env.OTEL_SDK_DISABLED aus. In JavaScript ist Boolean("false") true. Ohne Löschen von process.env.OTEL_SDK_DISABLED, wenn es nicht 'true' ist, deaktiviert das Setzen von OTEL_SDK_DISABLED=false das Tracing stillschweigend.
• Sekundäre benutzerdefinierte Flags: Führen Sie niemals OTEL_ENABLED zusätzlich zu OTEL_SDK_DISABLED ein. Standardisieren Sie strikt auf OTEL_SDK_DISABLED.
• Laufzeitüberschreitungen: Importieren Sie niemals instrumentation.ts oder Server-OpenTelemetry-SDKs in Client-Komponenten ("use client").
• Verkettete Befehle: Verketten Sie niemals Befehle (&&, ||, ;). Führen Sie alle Einrichtungs- und Testbefehle einzeln aus.

---

Ausgabe-Zusammenfassungsschema

Geben Sie nach Abschluss der OpenTelemetry-Einrichtung oder -Verifizierung einen strukturierten Bericht aus:

# OpenTelemetry Verifizierungsbericht

## Statuszusammenfassung

- **OTel-Status**: Aktiv / Deaktiviert
- **Service-Name**: <konfigurierter_service_name>
- **Ziel-Endpunkt**: <konfigurierter_endpunkt>
- **Exporter-Protokoll**: http/json | http/protobuf

## Verifizierungsergebnisse

| Prüfung                  | Erwartet                   | Tatsächlich         | Status |
| :----------------------- | :------------------------- | :------------------ | :----- |
| Initialisierungs-Hook    | Registriert                | Registriert         | PASS   |
| Trace-Versand (Aktiv)    | POST /v1/traces (200 OK)   | X Batches empfangen | PASS   |
| Kill-Switch (Deaktiviert) | Übersprungen, 0 Traces    | Übersprungen, 0     | PASS   |
| Typ-Prüfung              | 0 Fehler                   | 0 Fehler            | PASS   |

---

Referenzhandbücher & Vorlagen

• Architekturstandards-Referenz — Kill-Switch-Disziplin, Mechanik des Wahrheitsfehlers und Fehlerkontext.
• Verifizierungs- & Test-Runbook — Test-Harness-Anweisungen, curl-Auslöser und Kill-Switch-Verifizierung.
• Instrumentierungsvorlage — Vollständige instrumentation.ts mit Fehlerbehandlung.
• Umgebungskonfigurationsvorlage — Vollständige .env-Konfigurationsschlüssel.
• Mock Collector-Skript — Leichter Node.js OTLP HTTP Collector-Harness.