Add CLI telemetry commands (logs, spans, traces) by davidfowl · Pull Request #14256 · dotnet/aspire

davidfowl · 2026-01-30T17:01:53Z

Description

Adds new aspire telemetry commands to the CLI that consume the Dashboard Telemetry HTTP API, allowing users to query and stream telemetry data from the command line.

New Commands

aspire telemetry logs - View structured logs
aspire telemetry spans - View distributed trace spans
aspire telemetry traces - View distributed traces summary

Features

Filtering: Filter by resource, trace ID, severity (logs), error status (spans)
Pagination: --limit option to control number of results
Streaming: --follow option for real-time telemetry updates
Output formats: Table (default) and JSON (--format json)

Example Usage

aspire telemetry logs --limit 20
aspire telemetry logs orderprocessor --severity Error
aspire telemetry logs --follow

aspire telemetry spans --limit 10
aspire telemetry spans --resource frontend --follow

aspire telemetry traces --limit 5

Implementation Details

Uses v2 backchannel API to get Dashboard API URL and API token
Added TelemetryCommandHelpers.cs with shared code for all telemetry commands
Added ReadLinesAsync extension method on StreamReader for streaming support
Full localization support with resource strings

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
- No
Does the change make any security assumptions or guarantees?
- Yes
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire-docs issue: TODO: Create doc request for CLI telemetry commands
- No

github-actions · 2026-01-30T17:02:02Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 14256

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 14256"

Copilot

Pull request overview

This pull request adds comprehensive CLI telemetry commands that integrate with the Aspire Dashboard's Telemetry HTTP API, enabling users to query and stream telemetry data directly from the command line.

Changes:

Adds three new CLI commands: aspire telemetry logs, aspire telemetry spans, and aspire telemetry traces with filtering, pagination, and streaming support
Implements Dashboard API authentication via new DashboardApiKey configuration that is auto-generated and stored in user secrets
Refactors backchannel infrastructure to consolidate capability detection and connection initialization through a single factory method
Enhances Dashboard resource resolution to support both exact and base name matching for replica filtering

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs	Adds test service registrations for telemetry commands with test doubles for HTTP client and docs fetcher
tests/Aspire.Cli.Tests/TestServices/TestHttpClientFactory.cs	New test double providing basic HttpClient instances for testing
tests/Aspire.Cli.Tests/TestServices/TestDocsFetcher.cs	New test double returning empty docs content for testing
tests/Aspire.Cli.Tests/Commands/TelemetryCommandTests.cs	Comprehensive test coverage for all telemetry command variations and option combinations
src/Aspire.Hosting/DistributedApplicationBuilder.cs	Generates and stores DashboardApiKey in user secrets for API authentication
src/Aspire.Hosting/Dashboard/DashboardOptions.cs	Adds ApiKey property to dashboard configuration
src/Aspire.Hosting/Dashboard/DashboardEventHandlers.cs	Configures Dashboard API authentication with ApiKey fallback logic
src/Aspire.Hosting/Backchannel/DashboardUrlsHelper.cs	Refactored to return complete connection info including API endpoints and tokens
src/Aspire.Hosting/Backchannel/BackchannelDataTypes.cs	Adds ApiBaseUrl and ApiToken properties to dashboard info response
src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs	Updated to provide API connection info via v2 backchannel
src/Aspire.Dashboard/Model/Assistant/AIHelpers.cs	Enhanced resource resolution supporting base name matching for replica filtering
src/Aspire.Dashboard/Configuration/PostConfigureDashboardOptions.cs	Implements unidirectional API key fallback from Api to Mcp configuration
src/Aspire.Cli/Resources/TelemetryCommandStrings.*	Complete localization support with resource strings for all supported languages
src/Aspire.Cli/Program.cs	Registers new telemetry command services
src/Aspire.Cli/Commands/TelemetryCommand.cs	Parent command providing telemetry subcommand structure
src/Aspire.Cli/Commands/TelemetryLogsCommand.cs	Implements logs viewing with filtering, streaming, and table/JSON output
src/Aspire.Cli/Commands/TelemetrySpansCommand.cs	Implements spans viewing with trace correlation and real-time streaming
src/Aspire.Cli/Commands/TelemetryTracesCommand.cs	Implements trace visualization with hierarchical span tree display
src/Aspire.Cli/Commands/TelemetryCommandHelpers.cs	Shared utilities for API client creation, OTLP parsing, and stream processing
src/Aspire.Cli/Commands/RootCommand.cs	Integrates telemetry command into root command structure
src/Aspire.Cli/Backchannel/AuxiliaryBackchannelMonitor.cs	Refactored connection logic to use centralized factory method
src/Aspire.Cli/Backchannel/AppHostAuxiliaryBackchannel.cs	Consolidated connection creation with automatic capability detection via factory pattern

Files not reviewed (1)

src/Aspire.Cli/Resources/TelemetryCommandStrings.Designer.cs: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs

tests/Aspire.Cli.Tests/Commands/TelemetryCommandTests.cs

github-actions · 2026-01-30T17:43:54Z

🎬 CLI E2E Test Recordings

The following terminal recordings are available for commit 7cb1f04:

Test	Recording
CreateAndDeployToDockerCompose	▶️ View Recording
CreateAndDeployToDockerComposeInteractive	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateEmptyAppHostProject	▶️ View Recording
CreateStartAndStopAspireProject	▶️ View Recording
CreateTypeScriptAppHostWithViteApp	▶️ View Recording
DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording

_{📹 Recordings uploaded automatically from CI run #21581626488}

davidfowl · 2026-01-31T01:39:55Z

src/Aspire.Dashboard/Model/Assistant/AIHelpers.cs


-        if (!TryGetResource(resources, resourceName, out var resource))
+        // First, try exact match on a single resource
+        if (TryGetResource(resources, resourceName, out var resource))


This is the only dubious part of this change. Do we need to handle returning multiple replicas?

If the resource name is catalogservice and there are multiple instances then there should be an error and tell the user to be more specific. They need to specify catalogservice-abc123.

How would they know what the name is 😄. We need to take another look at replicate support

src/Aspire.Cli/Commands/TelemetryCommandHelpers.cs

src/Aspire.Cli/Commands/TelemetryLogsCommand.cs

JamesNK · 2026-01-31T13:25:37Z

src/Aspire.Cli/Commands/TelemetryLogsCommand.cs

+
+        if (format == OutputFormat.Json)
+        {
+            _interactionService.DisplayRawText(json);


Should the CLI validate the content-type is text/json? Or double check that text was returned.

src/Aspire.Cli/Commands/TelemetryLogsCommand.cs

src/Aspire.Cli/Commands/TelemetrySpansCommand.cs

davidfowl

Done - moved to shared OtlpHelpers.cs with ToShortenedId using 7 chars.

- Add 'aspire telemetry logs' command to view structured logs - Add 'aspire telemetry spans' command to view span details - Add 'aspire telemetry traces' command to view trace summaries - Support --follow for streaming logs and spans - Support --format json for machine-readable output - Consolidate Dashboard API URL builders in DashboardUrls.cs - Unify backchannel connection factory in CreateFromSocketAsync - Fix streaming API to filter all data when resource not found - Add tests for invalid resource streaming behavior

Copilot AI review requested due to automatic review settings January 30, 2026 17:01

Copilot started reviewing on behalf of davidfowl January 30, 2026 17:02 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs Outdated Show resolved Hide resolved

tests/Aspire.Cli.Tests/Commands/TelemetryCommandTests.cs Outdated Show resolved Hide resolved

github-actions bot mentioned this pull request Jan 30, 2026

[pull requests] Review required #13834

Open

davidfowl requested a review from mitchdenny as a code owner January 30, 2026 19:58

davidfowl commented Jan 31, 2026

View reviewed changes

davidfowl requested a review from JamesNK January 31, 2026 05:44

JamesNK reviewed Jan 31, 2026

View reviewed changes

davidfowl commented Feb 1, 2026

View reviewed changes

davidfowl force-pushed the davidfowl/telemetry-commands branch 2 times, most recently from 24015b4 to b043b13 Compare February 2, 2026 05:38

JamesNK approved these changes Feb 2, 2026

View reviewed changes

davidfowl enabled auto-merge (squash) February 2, 2026 07:21

davidfowl force-pushed the davidfowl/telemetry-commands branch from 8f0767b to 8108732 Compare February 2, 2026 07:46

davidfowl force-pushed the davidfowl/telemetry-commands branch from 8108732 to 7cb1f04 Compare February 2, 2026 07:47

davidfowl merged commit a646b56 into main Feb 2, 2026
658 of 663 checks passed

davidfowl deleted the davidfowl/telemetry-commands branch February 2, 2026 08:19

dotnet-policy-service bot added this to the 13.2 milestone Feb 2, 2026

MihuBot mentioned this pull request Feb 9, 2026

[✨ Triage] dotnet/aspire#14406 by davidfowl - Add a log and telemetry search command MihuBot/dotnet-triage#114

Open

MihuBot mentioned this pull request Mar 1, 2026

[✨ Triage] dotnet/aspire#14820 by davidfowl - Add a dashboard API and CLI commands to export/import traces/logs/metrics MihuBot/dotnet-triage#139

Open

github-actions bot locked and limited conversation to collaborators Mar 4, 2026

Conversation

davidfowl commented Jan 30, 2026

Description

New Commands

Features

Example Usage

Implementation Details

Checklist

Uh oh!

github-actions bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎬 CLI E2E Test Recordings

Uh oh!

davidfowl Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

JamesNK Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

davidfowl Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JamesNK Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidfowl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Jan 30, 2026 •

edited

Loading

github-actions bot commented Jan 30, 2026 •

edited

Loading