Next.js OpenTelemetry オブザーバビリティスキル（nextjs-otel）
Next.js App RouterアプリケーションでOpenTelemetryトレーシングを設定、テスト、検証するためのモジュール式で本番運用可能なワークフローです。単一のキルスイッチに統一し、@vercel/otelの初期化バグから保護し、トレース検証を自動化します。
ワークフロー概要
flowchart TD
A["1. プロジェクト評価<br/>（App Router & package.json）"] --> B["2. 依存関係のインストール<br/>（@vercel/otel & @opentelemetry/api）"]
B --> C["3. instrumentation.tsの展開<br/>（registerOTel + onRequestError）"]
C --> D["4. 環境設定<br/>（.env.example & .env.local）"]
D --> E["5. 検証とテストハーネス<br/>（モックコレクタ & キルスイッチ）"]
ステップバイステップ実行手順書
以下のチェックリストを順番に実行して、OpenTelemetryオブザーバビリティを設定・検証します。
1. プロジェクト発見と依存関係の検査
- プロジェクト構造の確認:
package.jsonのNext.js App Routerバージョンとパッケージマネージャー（pnpm、bun、npm）を確認します。 - インストルメンテーションルートの特定: プロジェクトがルートの
instrumentation.tsまたはsrc/instrumentation.tsを使用しているか確認します。 - アーキテクチャ標準の確認: architectural-standards.mdを参照し、単一キルスイッチの規律とランタイム境界を確認します。
2. 依存関係のインストール
- コアテレメトリーパッケージのインストール:
pnpm add @vercel/otel @opentelemetry/api
3. instrumentation.tsの展開
- インストルメンテーションファイルの作成: instrumentation.ts.templateをルートまたは
src/に展開します。 - 真偽値ガードの適用:
register()内で、process.env.OTEL_SDK_DISABLEDが厳密に"true"でない場合に削除し、@vercel/otelの真偽値評価バグを回避します。 - エラートラッキングの配線:
onRequestError()がnext.error.digest、ルートパス、HTTPメタデータをアクティブなスパンにキャプチャするようにします。
4. 環境変数の設定
- 環境テンプレートの更新: env.otel.templateを使用して、
.env.exampleと.env.localにOpenTelemetry設定を注入します。 - サービス名とプロトコルの設定:
OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOL=http/jsonを設定します。
5. 検証とテスト
- モックOTLPコレクタの起動: verification-and-testing.mdに従い、ポート4318でテストコレクタを起動します。
node .agents/skills/nextjs-otel/scripts/mock_collector.js - アクティブトレースの検証（
OTEL_SDK_DISABLED=false）: テストリクエスト（curl http://localhost:3000/）を実行し、POST /v1/tracesのバッチがHTTP 200 OKで送信されることを確認します。 - キルスイッチの検証（
OTEL_SDK_DISABLED=true）: Next.jsサーバーのログに[OTel] Instrumentation hook skippedが出力され、トレースが0件であることを確認します。 - 検証レポートの出力: Markdown形式のサマリーレポートを生成します。
エッジケースと既知のAI落とし穴
[!WARNING]
@vercel/otelの文字列真偽値バグ:@vercel/otelは!!process.env.OTEL_SDK_DISABLEDを評価します。JavaScriptではBoolean("false")はtrueです。process.env.OTEL_SDK_DISABLEDを'true'でない場合に削除しないと、OTEL_SDK_DISABLED=falseと設定してもトレーシングが静かに無効化されます。- セカンダリカスタムフラグ:
OTEL_SDK_DISABLEDと一緒にOTEL_ENABLEDを導入しないでください。厳密にOTEL_SDK_DISABLEDに統一します。- ランタイム境界違反:
instrumentation.tsやサーバーサイドのOpenTelemetry SDKをクライアントコンポーネント（"use client"）にインポートしないでください。- チェインコマンド: コマンドをチェイン（
&&、||、;）しないでください。すべてのセットアップおよびテストコマンドは個別に実行します。
出力サマリースキーマ
OpenTelemetryのセットアップまたは検証が完了したら、構造化レポートを出力します。
# OpenTelemetry 検証レポート
## ステータスサマリー
- **OTelステータス**: アクティブ / 無効
- **サービス名**: <設定されたサービス名>
- **ターゲットエンドポイント**: <設定されたエンドポイント>
- **エクスポータープロトコル**: http/json | http/protobuf
## 検証結果
| チェック項目 | 期待値 | 実際の値 | ステータス |
| :------------------------ | :------------------------- | :-------------------- | :--------- |
| 初期化フック | 登録済み | 登録済み | PASS |
| トレース送信（アクティブ）| POST /v1/traces (200 OK) | Xバッチ受信 | PASS |
| キルスイッチ（無効） | スキップ、0トレース | スキップ、0トレース | PASS |
| 型チェック | 0エラー | 0エラー | PASS |
リファレンスガイドとテンプレート
- アーキテクチャ標準リファレンス — キルスイッチの規律、真偽値バグの仕組み、エラーコンテキスト。
- 検証とテスト手順書 — テストハーネスの手順、curlトリガー、キルスイッチ検証。
- インストルメンテーションテンプレート — エラーハンドリングを含む完全な
instrumentation.ts。 - 環境設定テンプレート — 完全な
.env設定キー。 - モックコレクタスクリプト — 軽量Node.js OTLP HTTPコレクタハーネス。