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

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

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 accept --dashboard-url. The simplest form passes the full login URL printed by aspire dashboard run — the CLI normalizes it automatically:

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

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 or 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

If .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

Aspire Monitoring

Diagnostics Bridge — Where To Look