Aspire Monitoring

Aspire CLI provides full observability locally. For deployed apps, route to platform-specific tools.

Diagnostics Bridge — Where To Look

Need	Environment	Tool	Command / Route
Console logs	Local dev	Aspire CLI	`aspire logs <resource>`
Structured logs	Local dev	Aspire CLI	`aspire otel logs [resource]`
Distributed traces	Local dev	Aspire CLI	`aspire otel traces [resource]`
Span detail	Local dev	Aspire CLI	`aspire otel spans [resource]`
Resource state	Local dev	Aspire CLI	`aspire describe` (add `--include-hidden` if a resource is missing)
Telemetry export	Local dev	Aspire CLI	`aspire export [resource]`
Standalone dashboard	Any (no AppHost)	Aspire CLI	`aspire dashboard run` (foreground/blocking — see below)
Browser console / network / screenshots	Local dev (frontend)	Aspire dashboard	Surfaced via `Aspire.Hosting.Browsers` + `WithBrowserLogs()`
AppHost / deployment definition	Authoring	aspire-deployment skill	→ `aspire-deployment` skill
AKS workload (pod logs, pod state)	Deployed AKS	kubectl + Container Insights	`kubectl logs <pod>` , `kubectl describe pod <pod>` , Container Insights in Azure Monitor
Azure resource health (App Insights, Front Door, NSP, private endpoint)	Deployed Azure	azure-diagnostics	→ `azure-diagnostics` skill
App Service / Container Apps logs	Deployed Azure	azure-diagnostics	→ `azure-diagnostics` skill
Logs/state	Deployed Docker / Compose	Docker CLI	`docker logs <container>` , `docker compose logs <service>`

Decision tree:

Is this about AppHost code or deployment definition? →
```
aspire-deployment
```
skill.
Is the app running locally via
```
aspire start
```
? → Aspire CLI.
Is it deployed to AKS? → kubectl + Container Insights for workload;
```
azure-diagnostics
```
for the cluster's Azure resources.
Is it deployed to other Azure (App Service, Container Apps)? →
```
azure-diagnostics
```
.
Is it deployed to Docker / Compose? →
```
docker
```
/
```
docker compose
```
CLI.

See diagnostics-bridge.md for detailed routing.

Investigation Workflow

When something is wrong, investigate before editing code:

```
aspire describe
```
— check resource state and endpoints
```
aspire otel logs <resource>
```
— structured logs first
```
aspire logs <resource>
```
— console output as secondary view
```
aspire otel traces <resource>
```
— cross-service activity
```
aspire export
```
— zipped telemetry snapshot for deeper analysis

Local Commands Reference

Command	Purpose	Example
`aspire logs <resource>`	Console stdout/stderr	`aspire logs apiservice`
`aspire logs --follow`	Stream logs in real-time	`aspire logs apiservice --follow`
`aspire otel logs`	Structured OpenTelemetry logs	`aspire otel logs`
`aspire otel traces`	Distributed trace data	`aspire otel traces`
`aspire otel spans`	Individual span detail	`aspire otel spans`
`aspire otel logs --trace-id <id>`	Logs correlated to trace (⚠️ verify flag)	`aspire otel logs --trace-id abc123`
`aspire otel logs --dashboard-url`	Query a standalone dashboard (login URL or base URL + `--api-key` )	`aspire otel logs --dashboard-url "http://localhost:18888/login?t=TOKEN" --follow`
`aspire otel traces --dashboard-url`	Query a standalone dashboard	`aspire otel traces --dashboard-url "http://localhost:18888/login?t=TOKEN"`
`aspire describe`	Resource state, endpoints, health	`aspire describe --format Json`
`aspire describe --include-hidden`	Include proxies, helper containers, migrations	`aspire describe --include-hidden --format Json`
`aspire ps --format Json`	Resource list with state (filtered)	`aspire ps --format Json`
`aspire ps --include-hidden --format Json`	Resource list with hidden resources	`aspire ps --include-hidden --format Json`
`aspire export`	Portable telemetry bundle	`aspire export`
`aspire dashboard run`	Standalone dashboard (foreground/blocking)	`aspire dashboard run`

Hidden resources are filtered by default

aspire ps

aspire describe

, and other CLI commands filter out resources marked hidden in the AppHost (proxies, helper containers, migrations). The default output is correct for normal app inspection. Add

--include-hidden

when:

Debugging proxies, sidecar/helper containers, or migration jobs.
An expected resource is "missing" from
```
aspire ps
```
/
```
aspire describe
```
.
Triaging connectivity or wiring issues that may involve infrastructure resources.

Tips for Agents

bash

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

# ✅ When a resource you expect is missing, retry with --include-hidden
aspire ps --include-hidden --format Json | jq '.[] | {name, displayName, state, hidden}'

# ✅ 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/

Known Diagnostics Issues

Issue	Symptom	Workaround
TS AppHost DNS failure (#15782)	`aspire otel` "No such host" for `*.dev.localhost`	Use `--dashboard-url localhost:PORT`
`--isolated` mode telemetry (#16107)	OTEL port not randomized in isolated mode	Avoid `--isolated` if telemetry is needed
Resource missing from `aspire ps` / `aspire describe`	Hidden-by-default resources such as proxies, helpers, or migrations	Re-run with `--include-hidden`

Resolved in 13.3: The standalone-dashboard workaround for #16236 is obsolete — use
aspire dashboard run
(see below).

Standalone Dashboard (

aspire dashboard run

)

aspire dashboard run

launches the Aspire Dashboard without an AppHost, so any OTLP-emitting application (Aspire or not) can stream telemetry into it.

bash

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

⚠️ Foreground / blocking.
aspire dashboard run
does not return until you stop it (Ctrl-C). Agents must treat it as a long-running background process — start it with the bash tool's
mode="async"
, capture the dashboard URL and token from initial output, and leave it running. Do not invoke it as a one-shot synchronous command, and do not wait for it to "finish".

Connect the Aspire CLI to a standalone dashboard

aspire otel logs

and

aspire otel traces

--dashboard-url

. The simplest form passes the full login URL printed by

aspire dashboard run

— the CLI normalizes it automatically:

bash

# 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"

For dashboards configured with API-key authentication (e.g., the standalone container image with a separate API key), pass

--api-key

alongside the base

--dashboard-url

bash

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

The container-image standalone dashboard still works for environments where the CLI isn't available.

Browser Telemetry (

Aspire.Hosting.Browsers

)

The

Aspire.Hosting.Browsers

integration captures browser console logs, network requests, and screenshots from frontend resources during local development and surfaces them in the dashboard alongside server-side telemetry. Frontend resources opt in via

WithBrowserLogs()

Need	Action
Inspect browser telemetry that is already wired	Open the dashboard; browser logs / network / screenshots appear next to server telemetry for the resource
Confirm a frontend has it enabled	Check the AppHost for `.WithBrowserLogs()` on the resource (e.g., `AddViteApp("frontend").WithBrowserLogs()` )
Add `WithBrowserLogs()` to a resource	→ `aspireify` skill (AppHost authoring) — do not edit the AppHost from this skill

When parsing telemetry programmatically, browser logs surface as additional OTLP log records associated with the frontend resource —

aspire otel logs <frontend-resource>

returns them alongside server logs.

Dashboard UX Features

Agents inspecting a running dashboard should know:

Notification center (bell icon, top-right) — surfaces results of resource commands and lifecycle events. Inline command responses appear here instead of being scraped from the logs panel.
Rebuild command — available on container and project resources; rebuilds the image and restarts the resource without restarting the whole AppHost. Result lands in the notification center.
Structured command results — custom resource commands return
```
ExecuteCommandResult
```
with a
```
Message
```
payload that the dashboard renders inline; HTTP commands set
```
HttpCommandResultMode.Auto | Json | Text | None
```
to control how the response body is shown.

Authoring custom commands or
WithBrowserLogs()
calls is AppHost work — route to aspireify
. This skill is for observing what those features surface in the dashboard.

Why Aspire CLI Can't Do Remote Diagnostics

The Aspire CLI talks to a running AppHost through a local backchannel socket at

~/.aspire/backchannels/

. This is by design — there is no remote backchannel. For deployed apps, route to platform-specific tools (azure-diagnostics, kubectl, docker).

Exception: if a Dashboard is reachable (deployed alongside the app, or running standalone),

aspire otel logs

and

aspire otel traces

can query it via

--dashboard-url

(login URL form) and optional

--api-key

(see the Standalone Dashboard section above). This does not apply to

aspire logs

aspire describe

Handoff Rules

Scenario	Route To
Start/stop/wait/rebuild lifecycle	→ `aspire-orchestration` skill
Deploy, publish, pipeline steps, AppHost compute environment binding	→ `aspire-deployment` skill
AppHost code changes ( `WithBrowserLogs()` , custom commands, `WithHttpCommand` )	→ `aspireify` skill
Deployed Azure resource health (App Insights, Front Door, NSP, private endpoint, ACA, App Service)	→ `azure-diagnostics` skill (azure-skills)
AKS workload diagnostics (pod logs, pod state, Container Insights)	→ `kubectl` + Azure Monitor Container Insights
Docker / Compose container logs	→ `docker logs` / `docker compose logs`

Project-Local Skill Routing

.agents/skills/aspire/SKILL.md

exists (from

aspire agent init

), see its

references/monitoring.md

for deeper telemetry workflow guidance.

References

diagnostics-bridge.md — Local vs deployed routing detail
monitoring.md — Telemetry inspection and export patterns
playwright-handoff.md — Find the correct Aspire frontend URL before browser testing

aspire-monitoring

NPX Install

Tags

SKILL.md Content

Aspire Monitoring

Diagnostics Bridge — Where To Look

Investigation Workflow

Local Commands Reference

Hidden resources are filtered by default

Tips for Agents

Known Diagnostics Issues

Standalone Dashboard (
`aspire dashboard run`
)

Connect the Aspire CLI to a standalone dashboard

Browser Telemetry (
`Aspire.Hosting.Browsers`
)

Dashboard UX Features

Why Aspire CLI Can't Do Remote Diagnostics

Handoff Rules

Project-Local Skill Routing

References

aspire-monitoring

NPX Install

Tags

SKILL.md Content

Aspire Monitoring

Diagnostics Bridge — Where To Look

Investigation Workflow

Local Commands Reference

Hidden resources are filtered by default

Tips for Agents

Known Diagnostics Issues

Standalone Dashboard (aspire dashboard run)

Connect the Aspire CLI to a standalone dashboard

Browser Telemetry (Aspire.Hosting.Browsers)

Dashboard UX Features

Why Aspire CLI Can't Do Remote Diagnostics

Handoff Rules

Project-Local Skill Routing

References

Standalone Dashboard (
`aspire dashboard run`
)

Browser Telemetry (
`Aspire.Hosting.Browsers`
)