npx skills add ...
npx skills add microsoft/aspire-skills --skill aspire-monitoring
npx skills add microsoft/aspire-skills --skill aspire-monitoring
**ANALYSIS SKILL** - Observe Aspire apps: logs, traces, metrics, resource state, telemetry export, browser telemetry, and the standalone dashboard. Routes between local Aspire CLI, AKS workload diagnostics, and deployed Azure resource health. USE FOR: aspire logs, aspire otel logs, aspire otel traces, aspire otel spans, aspire describe, aspire ps, aspire export, aspire dashboard run, --include-hidden, browser logs in dashboard, WithBrowserLogs, App Insights query, AKS pod logs, container app logs. DO NOT USE FOR: start/stop/wait (use aspire-orchestration), deploy/publish/destroy (use aspire-deployment), AppHost code edits like WithBrowserLogs() (use aspireify), Azure provisioning (use azure-prepare). INVOKES: aspire CLI, azure-diagnostics (deployed Azure), kubectl + Container Insights. FOR SINGLE OPERATIONS: Run the aspire CLI command directly for quick log or describe lookups.
Aspire 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] |
| 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:
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 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 |
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:
aspire ps / aspire describe.| 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).
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.
⚠️ 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:
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:
The container-image standalone dashboard still works for environments where the CLI isn't available.
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.
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.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.
aspire dashboard run
# Dashboard: http://localhost:18888/login?t=<TOKEN>
# OTLP/gRPC: http://localhost:4317
# OTLP/HTTP: http://localhost:4318# 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"aspire otel logs --dashboard-url https://my-dashboard.example.com --api-key "$DASHBOARD_API_KEY" --follow