aspire-monitoring

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]
Running AppHosts	Local dev	Aspire CLI	aspire ps
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 / diagnostics	Local dev (frontend)	Aspire CLI + dashboard	Discover <frontend>-browser-logs, start its tracked browser, then inspect its console logs
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:

1. Is this about AppHost code or deployment definition? → aspire-deployment skill.
2. Is the app running locally via aspire start? → Aspire CLI.
3. Is it deployed to AKS? → kubectl + Container Insights for workload; azure-diagnostics for the cluster's Azure resources.
4. Is it deployed to other Azure (App Service, Container Apps)? → azure-diagnostics.
5. 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:

1. aspire describe — check resource state and endpoints
2. aspire otel logs <resource> — structured logs first
3. aspire logs <resource> — console output as secondary view
4. aspire otel traces <resource> — cross-service activity
5. 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 resources	Compatibility alias for resource state	Prefer aspire describe in new guidance
aspire export	Portable telemetry bundle	aspire export
aspire dashboard run	Standalone dashboard (foreground/blocking)	aspire dashboard run

Hidden resources are filtered by default

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 resources / aspire describe.
• Triaging connectivity or wiring issues that may involve infrastructure resources.

Tips for Agents

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

# ✅ When a resource you expect is missing, retry with --include-hidden
aspire describe --include-hidden --format Json

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

Version-Specific Diagnostics

Check the running dashboard version and actual error before applying a historical fix. An older fix does not establish that downgrading a newer dashboard is a working mitigation, even temporarily or in an isolated test.

Symptom	Guidance
Resource missing from aspire describe	Re-run aspire describe --include-hidden; do not use removed aspire ps --include-hidden.
DevTunnel is healthy but has no public URL on 13.5.0-13.5.2	Fixed in 13.5.3. Use a compatible release containing the fix before changing endpoint configuration.
Known multi-path icon Graph crash on 13.5.0-13.5.2	Fixed in 13.5.3. Use a compatible release containing the fix.
Dashboard Graph crashes on 13.5.3 or later	Keep the selected version. Capture the browser console stack trace and dashboard logs to diagnose a separate cause or regression; do not recommend installing 13.5.3 as a workaround.

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 Logs (Aspire.Hosting.Browsers)

When a frontend has already opted into WithBrowserLogs(), Aspire creates a child resource named <frontend>-browser-logs. Browser console messages, errors, exceptions, and network diagnostics are sent to that child resource's console log stream, not to the frontend's OpenTelemetry logs.

1. Begin with normal aspire describe or aspire resources output to find <frontend>-browser-logs; aspire ps no longer lists resources. It is a normal child resource, so retry with aspire describe --include-hidden only if unavailable.

2. Correlate it to the frontend through its parent relationship and Source property.

3. Start a tracked browser session with:

   aspire resource <frontend>-browser-logs open-tracked-browser
   

4. Inspect the browser diagnostics with:

   aspire logs <frontend>-browser-logs
   

Do not use aspire otel logs <frontend> for browser output; it does not return that child resource's browser diagnostics.

Need	Action
Inspect existing browser diagnostics	Discover <frontend>-browser-logs, start open-tracked-browser, then run aspire logs <frontend>-browser-logs
Confirm the browser resource belongs to a frontend	Check the child resource's parent relationship and Source property
Confirm a frontend has browser logging enabled	Check the AppHost for .WithBrowserLogs() on the resource
Add WithBrowserLogs() to a resource	→ aspireify skill (AppHost authoring) — do not edit the AppHost from this skill

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.
• 13.5 filtering — filter telemetry by timestamp, use == / != for exact numeric values, and search console-log text while streams continue updating.
• Terminal view — resources configured with experimental WithTerminal() open as interactive sessions in the dashboard.
• No dashboard AI Assistant — it was removed in 13.5. Use aspire agent init and the AppHost/CLI agent integration instead.
• VS Code launch is opt-in — the Aspire extension no longer opens the dashboard automatically. Use its in-editor dashboard or configure dashboardBrowser / launch.json.

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