Terminal
Terminal/Skill
Reads logs, traces, metrics, and resource state from a running Aspire app, using the Aspire CLI locally or platform tools for deployed apps.
By Microsoft
Works with
npx skills add microsoft/aspire-skills --skill aspire-monitoringAspire CLI provides full observability locally. For deployed apps, route to platform-specific tools.
| 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:
aspire-deployment skill.aspire start? → Aspire CLI.azure-diagnostics for the cluster's Azure resources.azure-diagnostics.docker / docker compose CLI.See diagnostics-bridge.md for detailed routing.
When something is wrong, investigate before editing code:
aspire describe — check resource state and endpointsaspire otel logs <resource> — structured logs firstaspire logs <resource> — console output as secondary viewaspire otel traces <resource> — cross-service activityaspire export — zipped telemetry snapshot for deeper analysis| 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 |
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:
aspire resources / aspire describe.# ✅ 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/
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).
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 rundoes not return until you stop it (Ctrl-C). Agents must treat it as a long-running background process — start it with the bash tool'smode="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".
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.
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.
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.
Correlate it to the frontend through its parent relationship and Source property.
Start a tracked browser session with:
aspire resource <frontend>-browser-logs open-tracked-browser
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 |
Agents inspecting a running dashboard should know:
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.== / != for exact numeric
values, and search console-log text while streams continue updating.WithTerminal() open as
interactive sessions in the dashboard.aspire agent init and the
AppHost/CLI agent integration instead.dashboardBrowser /
launch.json.Authoring custom commands or
WithBrowserLogs()calls is AppHost work — route toaspireify. This skill is for observing what those features surface in the dashboard.
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.
| 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 |
If .agents/skills/aspire/SKILL.md exists (from aspire agent init), see its
references/monitoring.md for deeper telemetry workflow guidance.