mcpField
O
observability

observability

github.com/serkan-ozal開発738 回インストール33 週間前に更新
リポジトリ

observability について

ブラウザーとバックエンドのツールを使って、Web アプリや Node.js アプリをデバッグするオブザーバビリティスキルです。トレースの関連付け、コンソールとネットワークの調査、Web Vitals の確認に対応します。

主な機能

  1. 01トレース ID の生成と設定
  2. 02ブラウザーのコンソールメッセージを確認
  3. 03HTTP リクエストを絞り込み
  4. 04Web Vitals の指標を取得
  5. 05フロントエンドとバックエンドのトレースを関連付け

活用シーン

  1. 01フロントエンドからバックエンドまでのリクエストを追跡
  2. 02ブラウザーのエラーや失敗したリクエストを調査
  3. 03アプリのデバッグ中に Web Vitals を確認

MCP 対応

Browser DevTools MCP の機能を使い、ブラウザーのトレース、コンソールメッセージ、HTTP リクエスト、Web Vitals を調べます。バックエンドのログ取得とトレース連携には node-devtools-cli を使う方法も説明しています。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/serkan-ozal/browser-devtools-skills --skill observability

インストール後、Claude Code で/observabilityを入力して読み込まれたか確認します。

詳細

可観測性スキル

OpenTelemetry、コンソールログ、ネットワークリクエスト、分散トレーシングを使用して、Web アプリケーションと Node.js アプリケーションを監視し、デバッグします。

使用するタイミング

このスキルは、次の場合に有効になります。

  • ユーザーが分散トレーシングについて質問した場合
  • ユーザーがフロントエンドとバックエンドのリクエストを関連付けたい場合
  • ユーザーが OpenTelemetry、Jaeger、Zipkin、またはトレーシングに言及した場合
  • ユーザーがサービス間のリクエストフローをデバッグする必要がある場合
  • ユーザーがアプリケーションの動作を監視したい場合

機能

分散トレーシング
browser-devtools-cli o11y get-trace-id
browser-devtools-cli o11y new-trace-id
browser-devtools-cli o11y set-trace-id --trace-id "abc123def456..."
コンソールの監視
browser-devtools-cli o11y get-console-messages
browser-devtools-cli --json o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-console-messages --search "error"
ネットワークの可観測性
browser-devtools-cli --json o11y get-http-requests
browser-devtools-cli --json o11y get-http-requests --resource-type fetch
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'
パフォーマンスメトリクス
browser-devtools-cli --json o11y get-web-vitals
browser-devtools-cli --json o11y get-web-vitals --wait-ms 3000
browser-devtools-cli --json o11y get-web-vitals --include-debug

OpenTelemetry の統合

トレースコンテキスト

Browser DevTools MCP は、W3C Trace Context ヘッダーを挿入および抽出できます。

  • traceparent：trace-id、span-id、トレースフラグを含みます
  • tracestate：ベンダー固有のトレース情報です
関連付けのフロー
Browser Session
    │
    ├─► trace-id: abc123
    │
    ▼
Frontend Request
    │
    ├─► Header: traceparent: 00-abc123-def456-01
    │
    ▼
Backend Service
    │
    ├─► Logs with trace-id: abc123
    │
    ▼
Observability Platform
    │
    └─► Full trace visualization
バックエンドの可観測性（node-devtools-cli）

フロントエンドのトレースとバックエンドの動作を関連付ける際は、node-devtools-cli を使用して Node.js プロセスを調査します。

# Connect to backend
node-devtools-cli --session-id backend debug connect --pid 12345

# Get console logs from Node process (can correlate with trace ID in logs)
node-devtools-cli --session-id backend --json debug get-logs
node-devtools-cli --session-id backend --json debug get-logs --search "trace"

# Optional: set tracepoints on backend handlers to capture call context
node-devtools-cli --session-id backend debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 25

デバッグのワークフロー

SESSION="--session-id trace-session"

# 1. Generate new trace ID
browser-devtools-cli $SESSION o11y new-trace-id

# 2. Navigate (requests will carry trace ID)
browser-devtools-cli $SESSION navigation go-to --url "https://app.example.com"
browser-devtools-cli $SESSION sync wait-for-network-idle

# 3. Perform actions
browser-devtools-cli $SESSION interaction click --selector "#submit"
browser-devtools-cli $SESSION sync wait-for-network-idle

# 4. Get trace ID for backend correlation
browser-devtools-cli $SESSION o11y get-trace-id

# 5. Check console errors
browser-devtools-cli $SESSION --json o11y get-console-messages --type error

# 6. Check network requests
browser-devtools-cli $SESSION --json o11y get-http-requests

# 7. Cleanup
browser-devtools-cli session delete trace-session

既存の Trace ID を使用する

SESSION="--session-id trace-session"

# Set trace ID from backend
browser-devtools-cli $SESSION o11y set-trace-id --trace-id "abc123def456789..."

# Navigate (requests will use this trace ID)
browser-devtools-cli $SESSION navigation go-to --url "https://app.example.com"

# All subsequent requests carry the trace ID
browser-devtools-cli $SESSION interaction click --selector "#api-call"

設定

環境変数
変数説明デフォルト
OTEL_ENABLEOpenTelemetry を有効化false
OTEL_SERVICE_NAMEサービス識別子frontend
OTEL_EXPORTER_TYPEエクスポート先none
OTEL_EXPORTER_HTTP_URLコレクターのエンドポイント-
OTEL_EXPORTER_HTTP_HEADERS認証ヘッダー-
エクスポーターの種類
種類説明
none無効
consoleコンソールにログを記録
otlp/httpOTLP コレクターに送信

一般的なプラットフォーム

Jaeger
OTEL_EXPORTER_HTTP_URL=http://localhost:4318
Grafana Tempo
OTEL_EXPORTER_HTTP_URL=http://tempo:4318
Honeycomb
OTEL_EXPORTER_HTTP_URL=https://api.honeycomb.io
OTEL_EXPORTER_HTTP_HEADERS=x-honeycomb-team=YOUR_API_KEY
Datadog
OTEL_EXPORTER_HTTP_URL=http://localhost:4318

ベストプラクティス

  1. 各テストシナリオで新しいトレース ID を生成する
  2. バグ報告にトレース ID を記載する
  3. JavaScript エラーがないか、まずコンソールを確認する
  4. 関連するエンドポイントにネットワークリクエストを絞り込む
  5. フロントエンドとバックエンドのタイムスタンプを関連付ける
  6. トレースコンテキストを含む構造化ログを使用する
  7. トレースを完全に可視化するため、OTEL エクスポーターを設定する

コメント

Markdown 対応