2026年5月5日のMicrosoft developer platform documentation updateでは、Aspire CLIでスタンドアロンのAspire Dashboardへ直接接続するための --dashboard-url と --api-key オプションが、aspire agent mcp と aspire otel logs/spans/traces のドキュメントに追加されました。結論から言うと、AppHostに管理されていないAspire Dashboardからログ・スパン・トレースをCLIやMCP経由で確認したい開発者は、接続先URLと認証方法を見直す必要があります。(GitHub)
これまで「Aspire Dashboardは動いているのに、CLIやAIエージェントからテレメトリを取りに行けない」と感じていた環境では、今回の更新が実務上かなり重要です。特に、ローカル開発、検証用の独立Dashboard、CIでの障害調査、MCP対応AIアシスタントからのログ確認を使っているチームは、この記事の手順に沿って設定を確認してください。
Microsoft developer platform documentation updateで何が変わったか
今回の更新は、MicrosoftのAspire関連ドキュメントに対するPRとして2026年5月5日にマージされました。対象は4つのCLIコマンド参照ページで、--dashboard-url <url>、--api-key <key>、スタンドアロンDashboard向けの使用例、aspire agent mcp のdashboard-only modeに関する説明が追加されています。(GitHub)
元になった実装変更は、aspire agent mcp と aspire otel logs、aspire otel spans、aspire otel traces に、スタンドアロンAspire Dashboardへ直接接続するためのオプションを追加するものです。従来のAppHost経由の探索だけでなく、CLI側でDashboard URLとAPIキーを指定できるようになりました。(GitHub)
| 観点 | これまでの課題 | 更新後の実務上の意味 |
|---|---|---|
| 接続先の指定 | AppHostからDashboard情報を取得する流れが前提になりやすい | --dashboard-url でスタンドアロンDashboardを直接指定できる |
| 認証 | セキュアなDashboardへのCLI接続が分かりにくい | --api-key で認証付きDashboardに接続できる |
| 対象コマンド | AppHost管理外のDashboardではログ・トレース確認がしづらい | aspire otel logs/spans/traces で直接クエリできる |
| MCP連携 | AIエージェントからDashboardだけを見たい場合の構成が曖昧 | aspire agent mcp --dashboard-url でテレメトリ専用のMCPモードを使える |
| エラー時の判断 | 401、404、接続失敗の原因を切り分けにくい | APIキー不足、API未有効、URL誤り、到達不能を判断しやすくなる |
追加されたオプションの使い分け
今回の中心は --dashboard-url と --api-key です。どちらも「Aspire Dashboardをブラウザで見る」ためではなく、「CLIやMCPサーバーからDashboard telemetry APIに接続する」ために使います。
| オプション | 役割 | 使う場面 | 注意点 |
|---|---|---|---|
--dashboard-url <url> | 接続先のスタンドアロンAspire Dashboardを指定する | AppHostに管理されていないDashboardからログ・スパン・トレースを取得したい場合 | --apphost とは同時に使えない |
--api-key <key> | セキュアなDashboardに認証して接続する | Dashboard telemetry APIがAPIキーを要求する場合 | コマンド履歴やログにAPIキーを残さない |
--apphost <apphost> | AppHostプロジェクトを指定する | 従来どおりAppHost管理下のDashboardを使う場合 | --dashboard-url と排他的に考える |
ドキュメント更新では、--dashboard-url にベースURLだけでなく、ブラウザトークンを含むログインURLも指定できる説明が追加されています。ログインURLが渡された場合、トークンをAPIキーへ交換する動きが説明されています。ただし、運用ではトークン付きURLをチームチャットやログに貼らないよう注意が必要です。(GitHub)
対応が必要な人、急がなくてよい人
今回のMicrosoft developer platform documentation updateは、すべてのAspire利用者が即日対応すべき変更ではありません。影響が大きいのは、AppHost管理外のDashboardを使っているチームです。
| 利用状況 | 対応優先度 | 確認すべきこと |
|---|---|---|
| スタンドアロンAspire Dashboardを使っている | 高 | --dashboard-url でログ・スパン・トレースを取得できるか確認する |
| MCP対応AIアシスタントからAspireのログやトレースを見たい | 高 | aspire agent mcp --dashboard-url のdashboard-only modeを試す |
CIや検証環境で aspire otel を使っている | 中 | AppHost依存のスクリプトをDashboard URL指定に置き換えられるか確認する |
通常の aspire run とAppHost管理下のDashboardだけを使っている | 低 | 既存運用は大きく変えなくてよい。将来のためにコマンド仕様を把握する |
| セキュアなDashboardをチームで共有している | 高 | APIキーの保管方法、ローテーション、ログ出力を確認する |
aspire otel logs は構造化ログ、aspire otel spans は分散トレース内の個々の処理単位、aspire otel traces はリクエスト全体の流れを確認するためのコマンドです。いずれもDashboard telemetry APIから情報を取得するため、接続先のDashboardと認証設定が正しくないと期待どおりに動きません。(Aspire)
移行・設定確認の基本手順
まずは、利用中のAspire CLIで新オプションが使えるか確認します。古いCLIや別チャネルのCLIを参照していると、ドキュメントどおりのオプションが表示されない場合があります。
aspire --version
aspire otel logs --help
aspire otel spans --help
aspire otel traces --help
aspire agent mcp --help--dashboard-url や --api-key が表示されない場合は、CLIの更新、PATHの向き先、利用チャネルを確認してください。チームで複数の開発端末やCIエージェントを使っている場合は、ローカルだけでなくCI側のCLIバージョンも確認するのがポイントです。
次に、スタンドアロンAspire DashboardのURLを確認します。ベースURLを使う場合は、次のように指定します。
aspire otel logs --dashboard-url "http://localhost:18888"ログインURLを使う場合は、トークン付きURLをそのまま指定できる説明がドキュメントに追加されています。
aspire otel traces --dashboard-url "http://localhost:18888/login?t=<token>" --limit 20セキュアなDashboardにAPIキーで接続する場合は、APIキーを直接コマンドに書くより、環境変数経由で渡す方が安全です。
$env:ASPIRE_DASHBOARD_API_KEY = "<your-api-key>"
aspire otel logs --dashboard-url "http://localhost:18888" --api-key $env:ASPIRE_DASHBOARD_API_KEYexport ASPIRE_DASHBOARD_API_KEY="<your-api-key>"
aspire otel traces --dashboard-url "http://localhost:18888" --api-key "$ASPIRE_DASHBOARD_API_KEY"調査対象が明確な場合は、リソース名、トレースID、エラー有無、出力形式を組み合わせます。
aspire otel logs apiservice --dashboard-url "http://localhost:18888" --severity Error --format Jsonaspire otel spans apiservice --dashboard-url "http://localhost:18888" --has-error true --format Jsonaspire otel traces --dashboard-url "http://localhost:18888" --trace-id "<trace-id>"JSON出力は、CIログの後処理、障害調査レポート、AIエージェントへの入力に向いています。一方、開発中に人が読むだけならTable出力の方が素早く状況を把握できます。
MCP利用時はdashboard-only modeを理解する
aspire agent mcp は、MCP対応クライアントやAIアシスタントがAspire環境とやり取りするためのMCPサーバーを起動するコマンドです。通常はリソース管理、診断、可観測性操作などを扱えます。(Aspire)
ただし、--dashboard-url を指定した場合はdashboard-only modeとして動作します。このモードでは、AppHost固有のリソース管理ツールは使えず、list_structured_logs、list_traces、list_trace_structured_logs の3つのテレメトリ系ツールだけが公開される説明になっています。(GitHub)
aspire agent mcp --dashboard-url "http://localhost:18888"認証が必要な場合は、APIキーも渡します。
aspire agent mcp --dashboard-url "http://localhost:18888" --api-key "<your-api-key>"ここで失敗しやすいのは、「MCPサーバーを起動したのに、リソースのstart/stop/restartができない」と判断してしまうケースです。--dashboard-url 指定時は、Dashboardだけに接続するテレメトリ専用モードです。AIアシスタントに作業させる場合も、「ログとトレースの確認は可能だが、AppHostリソース操作はできない」と前提を明確にしておくと、無駄な試行錯誤を減らせます。
エラー時の切り分けポイント
実装変更では、HTTP 401、HTTP 404、接続失敗に対するエラーメッセージ改善も含まれています。401では --api-key の利用を促し、404ではDashboard自体が到達可能かを確認して「APIが有効でない」のか「URLが間違っている」のかを切り分ける設計が説明されています。(GitHub)
| 症状 | よくある原因 | 確認・対処 |
|---|---|---|
--dashboard-url が認識されない | Aspire CLIが古い、または別のCLIを参照している | aspire --version と aspire otel logs --help を確認する |
| 401 Unauthorized | APIキーが未指定、期限切れ、誤り | --api-key を指定し、キーの発行元と権限を確認する |
| 404 Not Found | Dashboard URLのパスが違う、Telemetry APIが使えない | ベースURLかログインURLを指定しているか確認する |
| Connection refused | Dashboardが起動していない、ポートが違う、ネットワーク到達不可 | Dashboardの起動状態、ポート、プロキシ、ファイアウォールを確認する |
| MCPでリソース操作ツールが見えない | --dashboard-url によるdashboard-only modeで起動している | テレメトリ専用モードとして正常。リソース操作が必要ならAppHost経由にする |
--apphost と --dashboard-url を同時に指定して失敗する | 両者は排他的な接続方法 | AppHost管理下なら --apphost、独立Dashboardなら --dashboard-url を選ぶ |
障害調査では、まずブラウザでDashboardを開けるか、次にCLIで aspire otel logs --dashboard-url ... が通るか、最後にMCP連携を試す順番が安全です。いきなりMCPクライアント側の設定から疑うと、Dashboard URLやAPIキーの単純な誤りを見落としやすくなります。
接続方法の判断基準
実務では、「どのコマンドを使うか」より先に「DashboardがAppHost管理下かどうか」を判断すると整理しやすくなります。
| 状況 | 推奨する接続方法 | 理由 |
|---|---|---|
| AppHostを起動して通常のAspire開発をしている | 既存のAppHost経由 | 追加設定が少なく、リソース管理も使いやすい |
| AppHostとは別にDashboardを起動している | --dashboard-url | CLIから接続先を明示できる |
| セキュアなDashboardを使っている | --dashboard-url と --api-key | 認証付きのTelemetry APIへ接続できる |
| AIアシスタントにログ・トレースだけ見せたい | aspire agent mcp --dashboard-url | AppHost操作を公開せず、可観測性ツールに絞れる |
| CIで失敗時のログだけ収集したい | aspire otel logs --format Json | 後続処理やレポート化に使いやすい |
特にAIエージェント連携では、権限を絞れることが実務上のメリットです。AppHost全体を操作できるMCP構成より、Dashboardのテレメトリだけを読める構成の方が、調査目的に合う場面があります。
セキュリティ面で注意したいこと
--api-key は便利ですが、扱いを間違えると漏えいリスクがあります。次の点は、開発チームの運用ルールとして決めておくべきです。
| 注意点 | 具体的な対策 |
|---|---|
| シェル履歴にAPIキーが残る | 直接入力を避け、環境変数やシークレット管理を使う |
| CIログにAPIキーが出る | マスク設定を有効にし、デバッグ出力に注意する |
| ログインURLのトークンを共有してしまう | チャットやIssueに貼らない。必要なら短時間で無効化する |
| 権限範囲が広すぎる | 読み取り用途に限定できるなら限定する |
| キーを長期間使い回す | ローテーション手順を決め、退職者・異動者のアクセスを見直す |
また、--dashboard-url には内部ネットワークのDashboard URLを指定することがあります。開発用Dashboardを外部公開していないか、プロキシやトンネル経由で意図せずアクセス可能になっていないかも確認してください。
まとめ：まず確認すべき3点
今回のMicrosoft developer platform documentation updateは、Aspire CLIとスタンドアロンAspire Dashboardの接続を実務で使いやすくする更新です。重要なのは、新しいオプションを覚えることではなく、AppHost管理下のDashboardとスタンドアロンDashboardを使い分けられるようにすることです。
まず、手元とCIのAspire CLIで --dashboard-url と --api-key が使えるか確認してください。次に、DashboardのベースURL、ログインURL、APIキーのどれで接続する運用にするか決めます。最後に、aspire otel logs/spans/traces と aspire agent mcp の設定を見直し、MCP利用時はdashboard-only modeで使える機能範囲をチーム内で共有しておきましょう。
コメント