aspire-monitoring

Aspire のモニタリング

Aspire CLI は、ローカルで完全な可観測性を提供します。デプロイ済みのアプリでは、プラットフォーム固有のツールを使用してください。

診断ブリッジ — 確認先

必要なもの	環境	ツール	コマンド／ルート
コンソールログ	ローカル開発	Aspire CLI	aspire logs <resource>
構造化ログ	ローカル開発	Aspire CLI	aspire otel logs [resource]
分散トレース	ローカル開発	Aspire CLI	aspire otel traces [resource]
スパンの詳細	ローカル開発	Aspire CLI	aspire otel spans [resource]
実行中の AppHost	ローカル開発	Aspire CLI	aspire ps
リソースの状態	ローカル開発	Aspire CLI	aspire describe（リソースが見つからない場合は --include-hidden を追加）
テレメトリのエクスポート	ローカル開発	Aspire CLI	aspire export [resource]
スタンドアロンのダッシュボード	任意（AppHost なし）	Aspire CLI	aspire dashboard run（フォアグラウンドで実行され、処理をブロックします。下記を参照）
ブラウザーのコンソール／ネットワーク／診断	ローカル開発（フロントエンド）	Aspire CLI + ダッシュボード	<frontend>-browser-logs を検出し、追跡対象のブラウザーを起動してから、そのコンソールログを確認します
AppHost／デプロイ定義	作成時	aspire-deployment スキル	→ aspire-deployment スキル
AKS ワークロード（ポッドログ、ポッドの状態）	デプロイ済みの AKS	kubectl + Container Insights	kubectl logs <pod>、kubectl describe pod <pod>、Azure Monitor の Container Insights
Azure リソースの正常性（App Insights、Front Door、NSP、プライベートエンドポイント）	デプロイ済みの Azure	azure-diagnostics	→ azure-diagnostics スキル
App Service／Container Apps のログ	デプロイ済みの Azure	azure-diagnostics	→ azure-diagnostics スキル
ログ／状態	デプロイ済みの Docker／Compose	Docker CLI	docker logs <container>、docker compose logs <service>

判断フロー：

1. AppHost のコードまたはデプロイ定義に関する問題ですか？ → aspire-deployment スキル。
2. aspire start でアプリをローカル実行中ですか？ → Aspire CLI。
3. AKS にデプロイされていますか？ → ワークロードには kubectl + Container Insights、クラスターの Azure リソースには azure-diagnostics。
4. その他の Azure（App Service、Container Apps）にデプロイされていますか？ → azure-diagnostics。
5. Docker／Compose にデプロイされていますか？ → docker／docker compose CLI。

詳しいルーティングについては、diagnostics-bridge.md を参照してください。

調査ワークフロー

問題が発生した場合は、コードを編集する前に調査してください。

1. aspire describe — リソースの状態とエンドポイントを確認します
2. aspire otel logs <resource> — まず構造化ログを確認します
3. aspire logs <resource> — 補助的な確認手段としてコンソール出力を確認します
4. aspire otel traces <resource> — サービス間のアクティビティを確認します
5. aspire export — 詳細な分析に使う、ZIP 形式のテレメトリスナップショットを取得します

ローカルコマンドリファレンス

コマンド	用途	例
aspire logs <resource>	コンソールの標準出力／標準エラー	aspire logs apiservice
aspire logs --follow	ログをリアルタイムでストリーミングします	aspire logs apiservice --follow
aspire otel logs	構造化された OpenTelemetry ログ	aspire otel logs
aspire otel traces	分散トレースデータ	aspire otel traces
aspire otel spans	個々のスパンの詳細	aspire otel spans
aspire otel logs --trace-id <id>	トレースに関連付けられたログ（⚠️ フラグを確認してください）	aspire otel logs --trace-id abc123
aspire otel logs --dashboard-url	スタンドアロンのダッシュボードにクエリします（ログイン URL、またはベース URL と --api-key）	aspire otel logs --dashboard-url "http://localhost:18888/login?t=TOKEN" --follow
aspire otel traces --dashboard-url	スタンドアロンのダッシュボードにクエリします	aspire otel traces --dashboard-url "http://localhost:18888/login?t=TOKEN"
aspire describe	リソースの状態、エンドポイント、ヘルス	aspire describe --format Json
aspire describe --include-hidden	プロキシ、ヘルパーコンテナー、マイグレーションを含めます	aspire describe --include-hidden --format Json
aspire resources	リソースの状態を表示する互換性エイリアス	新しいガイダンスでは aspire describe を優先してください
aspire export	ポータブルなテレメトリバンドル	aspire export
aspire dashboard run	スタンドアロンのダッシュボード（フォアグラウンド／ブロッキング）	aspire dashboard run

非表示のリソースはデフォルトでフィルターされます

aspire describe およびその他の CLI コマンドでは、AppHost で非表示に設定されたリソース（プロキシ、ヘルパーコンテナー、マイグレーション）がフィルターされます。通常のアプリの確認には、デフォルトの出力で問題ありません。次の場合は --include-hidden を追加してください。

• プロキシ、サイドカー／ヘルパーコンテナー、またはマイグレーションジョブをデバッグする場合。
• 想定しているリソースが aspire resources ／ aspire describe に「表示されない」場合。
• インフラストラクチャリソースが関係している可能性のある接続または配線の問題をトリアージする場合。

エージェント向けのヒント

# ✅ Use --format Json for machine parsing (supported: describe, start)
aspire describe --format Json

# ✅ When a resource you expect is missing, retry with --include-hidden
aspire describe --include-hidden --format Json

# ✅ Get endpoints from describe, not guessing ports
ENDPOINT=$(aspire describe apiservice --format Json | jq -r '.endpoints[0].url')

# ✅ Use --apphost <path> when multiple AppHosts exist
aspire describe --apphost ./src/MyApp.AppHost/

バージョン固有の診断

過去の修正を適用する前に、実行中のダッシュボードのバージョンと実際のエラーを確認してください。 古いバージョン向けの修正が、新しいダッシュボードをダウングレードすることで、たとえ一時的または隔離されたテストであっても、問題を回避できることの根拠にはなりません。

症状	ガイダンス
aspire describe でリソースが見つからない	aspire describe --include-hidden を再実行してください。削除された aspire ps --include-hidden は使用しないでください。
13.5.0-13.5.2 で DevTunnel は正常だが、パブリック URL がない	13.5.3 で修正済みです。エンドポイント構成を変更する前に、修正を含む互換性のあるリリースを使用してください。
13.5.0-13.5.2 で既知の複数パスアイコンによる Graph クラッシュが発生する	13.5.3 で修正済みです。修正を含む互換性のあるリリースを使用してください。
13.5.3 以降でダッシュボードの Graph がクラッシュする	選択したバージョンを維持してください。別の原因またはリグレッションを診断するため、ブラウザーのコンソールスタックトレースとダッシュボードログを取得してください。回避策として 13.5.3 のインストールを推奨しないでください。

13.3 で解決済み： #16236 に対するスタンドアロンダッシュボードの回避策は不要になりました。aspire dashboard run を使用してください（下記参照）。

スタンドアロンダッシュボード（aspire dashboard run）

aspire dashboard run は AppHost なしで Aspire Dashboard を起動するため、OTLP を送信するアプリケーション（Aspire を使用するものも、使用しないものも）はテレメトリをストリーミングできます。

aspire dashboard run
# Dashboard:  http://localhost:18888/login?t=<TOKEN>
# OTLP/gRPC:  http://localhost:4317
# OTLP/HTTP:  http://localhost:4318

⚠️ フォアグラウンド／ブロッキングです。 aspire dashboard run は、停止するまで（Ctrl-C）戻りません。エージェントは、これを長時間実行するバックグラウンドプロセスとして扱う必要があります。bash ツールの mode="async" で起動し、初回出力からダッシュボードの URL とトークンを取得して、実行したままにしてください。単発の同期コマンドとして実行したり、「終了」するまで待ったりしないでください。

Aspire CLI をスタンドアロンダッシュボードに接続する

aspire otel logs と aspire otel traces は --dashboard-url を受け付けます。最も簡単な方法は、aspire dashboard run が出力する完全なログイン URL を渡すことです。CLI が自動的に正規化します。

# Stream structured logs from a standalone dashboard (login URL form)
aspire otel logs --dashboard-url "http://localhost:18888/login?t=TOKEN" --follow

# Search recent traces
aspire otel traces --dashboard-url "http://localhost:18888/login?t=TOKEN"

API キー認証を設定したダッシュボード（別途 API キーを指定するスタンドアロンのコンテナーイメージなど）の場合は、ベースとなる --dashboard-url とともに --api-key を渡します。

aspire otel logs --dashboard-url https://my-dashboard.example.com --api-key "$DASHBOARD_API_KEY" --follow

CLI を利用できない環境では、コンテナーイメージのスタンドアロンダッシュボードも引き続き使用できます。

ブラウザーログ（Aspire.Hosting.Browsers）

フロントエンドですでに WithBrowserLogs() が有効になっている場合、Aspire は <frontend>-browser-logs という名前の子リソースを作成します。ブラウザーのコンソールメッセージ、エラー、例外、ネットワーク診断は、フロントエンドの OpenTelemetry ログではなく、この子リソースのコンソールログストリームに送信されます。

1. 通常の aspire describe または aspire resources の出力から <frontend>-browser-logs を探します。aspire ps にはリソースが表示されなくなりました。通常の子 リソースなので、見つからない場合に限り aspire describe --include-hidden を試してください。

2. 親子関係と Source プロパティを使って、フロントエンドとの対応を確認します。

3. 次のコマンドで、追跡対象のブラウザーセッションを開始します。

   aspire resource <frontend>-browser-logs open-tracked-browser
   

4. 次のコマンドで、ブラウザーの診断情報を確認します。

   aspire logs <frontend>-browser-logs
   

ブラウザーの出力を取得するために aspire otel logs <frontend> を使用しないでください。このコマンドでは、その子リソースのブラウザー診断情報は返されません。

必要なこと	操作
既存のブラウザー診断情報を確認する	<frontend>-browser-logs を見つけ、open-tracked-browser を開始してから、aspire logs <frontend>-browser-logs を実行します
ブラウザーリソースがフロントエンドに属していることを確認する	子リソースの親子関係と Source プロパティを確認します
フロントエンドでブラウザーログが有効になっていることを確認する	リソースに .WithBrowserLogs() が設定されているか、AppHost を確認します
リソースに WithBrowserLogs() を追加する	→ aspireify スキル（AppHost の作成） — このスキルでは AppHost を編集しないでください

ダッシュボードの UX 機能

実行中のダッシュボードを調べるエージェントは、次の点を把握しておく必要があります。

• 通知センター（右上のベルアイコン）— リソースコマンドやライフサイクルイベントの結果を表示します。インラインのコマンド応答は、ログパネルから収集されるのではなく、ここに表示されます。
• リビルドコマンド — コンテナーリソースとプロジェクトリソースで使用できます。AppHost 全体を再起動せずに、イメージをリビルドしてリソースを再起動します。結果は通知センターに表示されます。
• 構造化されたコマンド結果 — カスタムリソースコマンドは Message ペイロードを含む ExecuteCommandResult を返し、ダッシュボードがインラインで表示します。HTTP コマンドでは HttpCommandResultMode.Auto | Json | Text | None を設定して、レスポンスボディの表示方法を制御します。
• 13.5 のフィルタリング — タイムスタンプでテレメトリをフィルタリングし、数値の完全一致には == / != を使用できます。また、ストリームの更新を続けながら、コンソールログのテキストを検索できます。
• ターミナルビュー — 実験的な WithTerminal() を設定したリソースは、ダッシュボードで対話型セッションとして開きます。
• ダッシュボードの AI アシスタントはありません — 13.5 で削除されました。代わりに aspire agent init と AppHost／CLI のエージェント統合を使用してください。
• VS Code の起動はオプトイン方式です — Aspire 拡張機能はダッシュボードを自動的に開かなくなりました。エディター内のダッシュボードを使用するか、dashboardBrowser / launch.json を設定してください。

カスタムコマンドの作成や WithBrowserLogs() の呼び出しは AppHost での作業です。aspireify に引き継いでください。このスキルは、そうした機能がダッシュボードに表示する内容を確認するためのものです。

Aspire CLI でリモート診断を行えない理由

Aspire CLI は、~/.aspire/backchannels/ のローカルバックチャネルソケットを介して、実行中の AppHost と通信します。これは 仕様によるもの であり、リモートバックチャネルはありません。デプロイ済みのアプリでは、プラットフォーム固有のツール（azure-diagnostics、kubectl、docker）を使用してください。

例外：Dashboard に到達できる場合（アプリと一緒にデプロイされている、またはスタンドアロンで実行されている場合）、aspire otel logs と aspire otel traces は、--dashboard-url（ログイン URL 形式）と任意の --api-key を指定してクエリできます（上記のスタンドアロン Dashboard のセクションを参照してください）。これは aspire logs や aspire describe には 適用されません。

引き継ぎルール

シナリオ	引き継ぎ先
起動／停止／待機／再ビルドのライフサイクル	→ aspire-orchestration スキル
デプロイ、公開、パイプラインの手順、AppHost のコンピューティング環境へのバインド	→ aspire-deployment スキル
AppHost のコード変更（WithBrowserLogs()、カスタムコマンド、WithHttpCommand）	→ aspireify スキル
デプロイ済み Azure リソースの正常性（App Insights、Front Door、NSP、プライベートエンドポイント、ACA、App Service）	→ azure-diagnostics スキル（azure-skills）
AKS ワークロードの診断（Pod のログ、Pod の状態、Container Insights）	→ kubectl + Azure Monitor Container Insights
Docker／Compose コンテナーのログ	→ docker logs / docker compose logs

プロジェクトローカルのスキルへのルーティング

.agents/skills/aspire/SKILL.md（aspire agent init によって作成）が存在する場合は、 より詳しいテレメトリのワークフローに関するガイダンスについて、その中の references/monitoring.md を参照してください。

参考資料

• diagnostics-bridge.md — ローカルとデプロイ済み環境のルーティングの詳細
• monitoring.md — テレメトリの調査とエクスポートのパターン
• playwright-handoff.md — ブラウザテストの前に適切な Aspire フロントエンド URL を見つける方法