Skip to content

ecoDriverltd/FoundryAgentsExperiment / .agents/skills/aspire-monitoring

aspire-monitoring

Verified

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

FileKindSize
SKILL.mdskill md12.2 KB
references/diagnostics-bridge.mdmarkdown11.2 KB
references/monitoring.mdmarkdown8.4 KB
references/playwright-handoff.mdmarkdown963 B

references/diagnostics-bridge.md

View on GitHub
# Diagnostics Bridge — Local vs Deployed

> **Purpose**: Route diagnostics requests to the correct tool based on where the application is running.

## Decision Flowchart

```
Is the request about AppHost code or deployment definition?
│
├── YES → Route to aspire-deployment skill (and aspireify for code edits)
│
└── NO → Is the app running locally (via aspire start)?
    │
    ├── YES → Use Aspire CLI
    │   ├── Console logs       → aspire logs <resource>
    │   ├── Structured logs    → aspire otel logs
    │   ├── Traces             → aspire otel traces
    │   ├── Spans              → aspire otel spans
    │   ├── Resource state     → aspire describe   (add --include-hidden if missing)
    │   ├── Export telemetry   → aspire export
    │   ├── Filter by trace    → aspire otel logs --trace-id <id> (verify flag)
    │   └── Standalone dash    → aspire dashboard run  (foreground/blocking)
    │
    └── NO (deployed) → Route by target
        ├── Azure Kubernetes Service (AKS)
        │   ├── Pod logs           → kubectl logs <pod>
        │   ├── Pod / workload state → kubectl describe pod <pod>, kubectl get pods
        │   ├── Cluster Azure resources → azure-diagnostics skill
        │   └── Cluster-wide telemetry → Azure Monitor Container Insights
        │
        ├── Other Azure (App Service, Container Apps) → azure-diagnostics skill
        │   ├── App logs           → az containerapp logs show / az webapp log tail
        │   ├── Metrics            → az monitor metrics list
        │   ├── App Insights       → az monitor app-insights query
        │   ├── Resource health    → az resource show / AppLens
        │   └── Front Door / NSP / private endpoint → azure-diagnostics
        │
        └── Docker / Compose → Use Docker tooling
            ├── Container logs     → docker logs <container>
            ├── Service logs       → docker compose logs <service>
            └── Resource state     → docker ps / docker compose ps
```

---

## Local Development — Full Aspire CLI Support

When the app is running locally via `aspire start`, the Aspire CLI provides complete observability:

### How It Works

The Aspire CLI communicates with the running AppHost through a **backchannel socket** at `~/.aspire/backchannels/`. This is a local-only IPC mechanism — it cannot connect to remote instances.

### Available Commands

| Command | Purpose | Example |
|---------|---------|---------|
| `aspire logs <resource>` | Console stdout/stderr from a resource | `aspire logs apiservice` |
| `aspire logs --follow` | Stream logs in real-time | `aspire logs apiservice --follow` |
| `aspire otel logs` | Structured OpenTelemetry log records | `aspire otel logs` |
| `aspire otel traces` | Distributed trace data | `aspire otel traces` |
| `aspire otel spans` | Individual span-level detail | `aspire otel spans` |
| `aspire otel logs --trace-id <id>` | Logs correlated to a specific trace (⚠️ verify flag in your version) | `aspire otel logs --trace-id abc123` |
| `aspire otel logs --dashboard-url` | Query a standalone or deployed dashboard | `aspire otel logs --dashboard-url "https://localhost:18888/login?t=TOKEN"` |
| `aspire describe` | Resource state, endpoints, health (filtered) | `aspire describe --format Json` |
| `aspire describe --include-hidden` | Include hidden resources (proxies, helpers, migrations) | `aspire describe --include-hidden --format Json` |
| `aspire ps --include-hidden --format Json` | Resource list including hidden resources | `aspire ps --include-hidden --format Json` |
| `aspire export` | Export portable telemetry bundle | `aspire export` |
| `aspire dashboard run` | Run the Aspire Dashboard standalone (foreground/blocking) | `aspire dashboard run` |

### Tips for Agents

```bash
# ✅ Always use --format Json for machine parsing
aspire describe --format Json

# ✅ When an expected resource is missing, retry with --include-hidden
#    Hidden-by-default resources (proxies, helper containers, migrations)
aspire ps --include-hidden --format Json

# ✅ Get endpoints from describe, not guessing ports
ENDPOINT=$(aspire describe apiservice --format Json | jq -r '.endpoints[0].url')

# ✅ Correlate logs to a specific request
aspire otel logs --trace-id <trace-id-from-otel-traces>
```

---

## Standalone Dashboard — `aspire dashboard run`

`aspire dashboard run` runs the Aspire Dashboard without an AppHost — point any OTLP-emitting application at it (Aspire or not) and telemetry shows up live.

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

> ⚠️ **Foreground / blocking.** This command does not return until you stop it (Ctrl-C). Agents must start it as a long-running background process (e.g., bash `mode="async"`), capture the dashboard URL and `t=` token from initial output, and leave it running. Do **not** treat it as a one-shot synchronous command.

### Connect the CLI to a standalone dashboard

The `aspire otel logs` and `aspire otel traces` commands accept `--dashboard-url` (and `--api-key` when the dashboard is configured with API-key auth) so the CLI can query a standalone dashboard without an AppHost.

The simplest form passes the full login URL printed by `aspire dashboard run` — the CLI normalizes login URLs automatically:

```bash
# Stream structured logs (login URL form — token in URL)
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 that use a separate API key (e.g., the standalone container image with API-key auth configured), pass `--api-key` alongside the base URL:

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

The container-image standalone dashboard is still available where the CLI isn't an option.

---

## Browser Telemetry (`Aspire.Hosting.Browsers`)

The `Aspire.Hosting.Browsers` integration captures **browser console logs, network requests, and screenshots** from frontend resources during local development. Frontend resources opt in by calling `WithBrowserLogs()` in the AppHost. The data shows up in the dashboard alongside server-side telemetry.

| Need | Action |
|------|--------|
| Inspect existing browser telemetry | Open the dashboard or run `aspire otel logs <frontend-resource>` |
| Check whether a frontend has it enabled | Look for `.WithBrowserLogs()` in the AppHost |
| Add `WithBrowserLogs()` to a resource | → **`aspireify` skill** (AppHost authoring) |

---

## Deployed Applications — Routing

### Why Aspire CLI Cannot Help Directly

The Aspire CLI's `aspire logs`, `aspire describe`, and other backchannel commands use the local backchannel socket at `~/.aspire/backchannels/`. This is **by design** — there is no remote backchannel. When an app is deployed, the Aspire CLI cannot reach it directly.

**Exception:** if a Dashboard is reachable (deployed alongside the app, or running standalone), `aspire otel logs --dashboard-url` and `aspire otel traces --dashboard-url` (with `--api-key` when the dashboard requires it) can query it remotely. This does **not** extend to `aspire logs` or `aspire describe`.

```bash
# Limited remote support via deployed Dashboard — login URL form
aspire otel logs --dashboard-url "https://my-dashboard.azurecontainerapps.io/login?t=TOKEN"
aspire otel traces --dashboard-url "https://my-dashboard.azurecontainerapps.io/login?t=TOKEN"

# Or with separate API-key auth
aspire otel logs --dashboard-url https://my-dashboard.azurecontainerapps.io --api-key "$DASHBOARD_API_KEY"
```

### Three-way deployed routing

| Target | Use | Examples |
|--------|-----|----------|
| **AKS workload (pod logs, pod state, container insights)** | `kubectl` + Azure Monitor Container Insights | `kubectl logs <pod>`, `kubectl describe pod <pod>`, Container Insights queries |
| **Azure resource health** (App Insights, Front Door, NSP, private endpoint, ACA, App Service) | `azure-diagnostics` skill (azure-skills) | `az containerapp logs show`, `az monitor app-insights query`, AppLens |
| **Docker / Compose** | Docker CLI | `docker logs <container>`, `docker compose logs <service>` |

### azure-diagnostics — quick reference

| Need | azure-diagnostics Approach |
|------|---------------------------|
| Application logs | `az containerapp logs show --name APP -g RG --follow` |
| Metrics | `az monitor metrics list --resource RESOURCE_ID` |
| App Insights queries | `az monitor app-insights query --analytics-query "KQL"` |
| Resource health | AppLens MCP tool or `az resource show` |
| Activity log | `az monitor activity-log list -g RG` |
| Front Door / NSP / private endpoint | `az network front-door`, `az network perimeter`, AppLens |

### Production Telemetry — Automatic Configuration

Aspire auto-configures Application Insights when `AddAzureApplicationInsights()` is used in the AppHost. Deployed apps export OpenTelemetry data to App Insights automatically, providing:

- Request traces and dependency tracking
- Exception logging
- Performance metrics
- Live Metrics stream
- Application Map (service topology)

No additional configuration is needed — Aspire wires the connection string during deployment.

## Known Diagnostics Issues

| Issue | Symptom | Workaround |
|-------|---------|-----------|
| TS AppHost DNS failure ([#15782](https://github.com/microsoft/aspire/issues/15782)) | `aspire otel` returns "No such host" for `*.dev.localhost` | Use `--dashboard-url localhost:PORT` directly |
| `--isolated` mode telemetry ([#16107](https://github.com/microsoft/aspire/issues/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](https://github.com/microsoft/aspire/issues/16236) is obsolete — `aspire dashboard run` ships in-box (see Standalone Dashboard section above).

---

## Summary: Where to Look

| Question | Local Dev | Deployed |
|----------|-----------|----------|
| "What's the status of my resources?" | `aspire describe` (try `--include-hidden` if missing) | Azure Portal / `az containerapp show` / `kubectl describe pod` |
| "Show me the logs" | `aspire logs <resource>` | `az containerapp logs show` / `kubectl logs <pod>` / `docker logs` |
| "Show me distributed traces" | `aspire otel traces` | App Insights → Transaction Search |
| "Why is this resource unhealthy?" | `aspire describe` + `aspire logs` | AppLens / azure-diagnostics / `kubectl describe pod` |
| "What metrics are available?" | Aspire Dashboard (auto-launched or `aspire dashboard run`) | Azure Monitor / App Insights / Container Insights |
| "Export telemetry for analysis" | `aspire export` | App Insights export / KQL query |
| "Browser console / network logs" | Dashboard (with `WithBrowserLogs()` enabled) — N/A in production |
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall