Add --dashboard-url and --api-key options to aspire agent mcp and aspire otel commands#15595
Open
Add --dashboard-url and --api-key options to aspire agent mcp and aspire otel commands#15595
Conversation
Contributor
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 15595Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 15595" |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds support for connecting the CLI telemetry (“otel”) and MCP agent directly to a standalone Aspire Dashboard via --dashboard-url (and optional --api-key), instead of requiring AppHost discovery/backchannel.
Changes:
- Introduces
IDashboardInfoProviderand updates MCP telemetry tools to use it (backchannel vs. static URL/key). - Adds
--dashboard-url/--api-keyoptions toaspire otel logs|spans|tracesand adds smarter dashboard-specific error messaging. - Adds “dashboard-only” MCP mode that exposes only telemetry MCP tools when started with
--dashboard-url, plus new/updated tests and localized strings.
Reviewed changes
Copilot reviewed 29 out of 30 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/Aspire.Cli.Tests/Mcp/ListTracesToolTests.cs | Updates tool construction to use IDashboardInfoProvider. |
| tests/Aspire.Cli.Tests/Mcp/ListStructuredLogsToolTests.cs | Updates tool construction to use IDashboardInfoProvider. |
| tests/Aspire.Cli.Tests/Commands/TelemetryTracesCommandTests.cs | Adds tests for --dashboard-url behavior and 401 guidance. |
| tests/Aspire.Cli.Tests/Commands/TelemetrySpansCommandTests.cs | Adds tests for --dashboard-url behavior and 401 guidance. |
| tests/Aspire.Cli.Tests/Commands/TelemetryLogsCommandTests.cs | Adds tests for direct dashboard mode, api-key header, 404 probing, and connection errors. |
| tests/Aspire.Cli.Tests/Commands/AgentMcpCommandTests.cs | Refactors MCP test setup and adds dashboard-only mode tests. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.zh-Hant.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.zh-Hans.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.tr.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.ru.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.pt-BR.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.pl.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.ko.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.ja.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.it.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.fr.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.es.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.de.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/xlf/TelemetryCommandStrings.cs.xlf | Adds localized entries for new options/error messages. |
| src/Aspire.Cli/Resources/TelemetryCommandStrings.resx | Adds new resource strings for options and dashboard-specific errors. |
| src/Aspire.Cli/Resources/TelemetryCommandStrings.Designer.cs | Regenerates strongly-typed accessors for new resource strings. |
| src/Aspire.Cli/Mcp/Tools/ListTracesTool.cs | Switches to IDashboardInfoProvider and uses shared dashboard error message helper. |
| src/Aspire.Cli/Mcp/Tools/ListTraceStructuredLogsTool.cs | Switches to IDashboardInfoProvider and uses shared dashboard error message helper. |
| src/Aspire.Cli/Mcp/Tools/ListStructuredLogsTool.cs | Switches to IDashboardInfoProvider and uses shared dashboard error message helper. |
| src/Aspire.Cli/Mcp/Tools/IDashboardInfoProvider.cs | Adds provider abstraction + backchannel/static implementations. |
| src/Aspire.Cli/Commands/TelemetryTracesCommand.cs | Adds --dashboard-url/--api-key support and dashboard-mode error messaging. |
| src/Aspire.Cli/Commands/TelemetrySpansCommand.cs | Adds --dashboard-url/--api-key support and dashboard-mode error messaging. |
| src/Aspire.Cli/Commands/TelemetryLogsCommand.cs | Adds --dashboard-url/--api-key support and dashboard-mode error messaging. |
| src/Aspire.Cli/Commands/TelemetryCommandHelpers.cs | Adds option factories, validates exclusivity, adds direct dashboard mode + richer error messages. |
| src/Aspire.Cli/Commands/AgentMcpCommand.cs | Adds dashboard-only MCP mode with --dashboard-url/--api-key and tool filtering. |
Files not reviewed (1)
- src/Aspire.Cli/Resources/TelemetryCommandStrings.Designer.cs: Language not supported
Comment on lines
+168
to
+176
| if (dashboardUrl is not null) | ||
| { | ||
| var errorMessage = await TelemetryCommandHelpers.GetDashboardApiErrorMessageAsync(ex, baseUrl, _httpClientFactory, _logger, cancellationToken); | ||
| _interactionService.DisplayError(errorMessage); | ||
| } | ||
| else | ||
| { | ||
| _interactionService.DisplayError(string.Format(CultureInfo.CurrentCulture, TelemetryCommandStrings.FailedToFetchTelemetry, ex.Message)); | ||
| } |
There was a problem hiding this comment.
In --dashboard-url mode a 404 can indicate "wrong URL" or "telemetry API not enabled", but FetchSingleTraceAsync still special-cases response.StatusCode == NotFound earlier and returns "Trace not found" before this new dashboard-url error handling runs. Consider gating the TraceNotFound early-return to AppHost mode only, and let 404s in --dashboard-url mode flow through GetDashboardApiErrorMessageAsync.
Comment on lines
+221
to
+228
| using var probeClient = httpClientFactory.CreateClient(); | ||
| var probeResponse = await probeClient.GetAsync(dashboardBaseUrl, cancellationToken).ConfigureAwait(false); | ||
|
|
||
| if (probeResponse.IsSuccessStatusCode) | ||
| { | ||
| // Dashboard is reachable but the API endpoint returned 404 — API not enabled | ||
| return string.Format(CultureInfo.CurrentCulture, TelemetryCommandStrings.DashboardApiNotEnabled, dashboardBaseUrl); | ||
| } |
There was a problem hiding this comment.
GetDashboardApiErrorMessageAsync probes the base URL with probeClient.GetAsync(...) but never disposes the HttpResponseMessage. Even though this is an error path, not disposing responses can hold onto connections longer than necessary. Wrap the probe response in a using (or await using) to ensure it is disposed promptly.
JamesNK
force-pushed
the
cli-dashboard-url-apikey
branch
4 times, most recently
from
76f22b6 to
11c3eac
Compare
…ire otel commands Add support for connecting directly to a standalone Aspire Dashboard without an AppHost via --dashboard-url and optional --api-key options on the 'aspire agent mcp' and 'aspire otel logs/spans/traces' commands. - Introduce IDashboardInfoProvider abstraction (BackchannelDashboardInfoProvider and StaticDashboardInfoProvider) to decouple MCP tools from the backchannel - Add --dashboard-url and --api-key options to TelemetryLogs/Spans/TracesCommand - Add dashboard-only mode to AgentMcpCommand (exposes only telemetry tools) - Add smart error handling: 401 suggests --api-key, 404 checks if API is enabled, connection refused reports unreachable dashboard - Add tests for all new functionality
…cate error handling - Add IsDirectConnection to IDashboardInfoProvider so MCP tools only show dashboard-url-specific error messages (e.g. --api-key hint) when actually using --dashboard-url, not in AppHost backchannel mode - Validate --dashboard-url accepts only http/https schemes in both AgentMcpCommand and TelemetryCommandHelpers - Extract duplicated if/else error handling from 5 catch blocks in otel commands into TelemetryCommandHelpers.FormatTelemetryErrorMessageAsync
Contributor
|
How does the agent get the API key from the CLI or is it expected that the user gives it after the agent sees the 401? Can you share a video of the flow? |
JamesNK
force-pushed
the
cli-dashboard-url-apikey
branch
from
8aa7b47 to
c502d9a
Compare
Member
Author
If the agent started the dashboard then it would have passed an API key in, so would have it that way. This has good error handling so if auth fails then there will be clear feedback to the agent/user that an API key is needed and how to give it to the command. |
Contributor
|
Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
|
- ExportCommand supports --dashboard-url and --api-key for direct dashboard access - Refactor GetDashboardApiAsync to return DashboardApiResult record with Connection - Add requireDashboard parameter to GetDashboardApiAsync for optional dashboard - Update ExportCommand to gracefully degrade when dashboard is unavailable - Add DisplayedMessages tracking to TestInteractionService - Add ExportCommand_DashboardUnavailable test using TestInteractionService - Simplify CreateExportTestServices: remove outputWriter param, add interactionService
Verifies export command works with --dashboard-url and --api-key options, bypassing AppHost backchannel discovery and fetching telemetry data directly from the dashboard API.
Contributor
|
🎬 CLI E2E Test Recordings — 52 recordings uploaded (commit View recordings
📹 Recordings uploaded automatically from CI run #23591840590 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add
--dashboard-urland--api-keyoptions to theaspire agent mcpandaspire otel logs/spans/tracescommands, enabling direct connection to a standalone Aspire Dashboard without requiring an AppHost.Motivation: Users running a standalone Aspire Dashboard (not managed by an AppHost) currently have no way to query telemetry data through the CLI or MCP tools. This change allows pointing the CLI directly at a dashboard URL.
Key changes:
IDashboardInfoProviderabstraction — New interface with two implementations:BackchannelDashboardInfoProvider(existing AppHost flow) andStaticDashboardInfoProvider(CLI-provided URL/key). MCP tools now depend on this abstraction instead ofIAuxiliaryBackchannelMonitordirectly.--dashboard-urland--api-keyon otel commands —aspire otel logs,aspire otel spans, andaspire otel tracesaccept an optional dashboard URL (mutually exclusive with--apphost) and optional API key for secured dashboards.aspire agent mcp --dashboard-urlstarts the MCP server exposing only the three telemetry tools (list_structured_logs,list_traces,list_trace_structured_logs), filtering out AppHost-specific tools.--api-key, HTTP 404 probes the base URL to distinguish "API not enabled" vs "wrong URL", and connection failures report the dashboard as unreachable.AgentMcpCommandTeststo remove fields and use a reusable helper method.Validation: All 1728 CLI tests pass (0 failures, 5 platform-specific skips).
Fixes # (issue)
Checklist
<remarks />and<code />elements on your triple slash comments?aspire.devissue: