brianj/silver-octo-spoon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added A-Frame Architecture Sample.

Browse Source
This commit is contained in:
brianj
2026-06-08 20:19:41 +02:00
parent b2d7e7e26b
commit 6760f90336
63 changed files with 5075 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AFrameArchitectureSample/.agents/skills/aspire-monitoring/SKILL.md
+197
View File
@@ -0,0 +1,197 @@
---
name: aspire-monitoring
description: >-
**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.
license: MIT
metadata:
author: Microsoft
version: "0.0.1"
---
# 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]` |
| 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:**
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](references/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 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
```bash
# ✅ 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](https://github.com/microsoft/aspire/issues/15782)) | `aspire otel` "No such host" for `*.dev.localhost` | Use `--dashboard-url localhost:PORT` |
| `--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 — 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.
```bash
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:
```bash
# 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`:
```bash
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](references/diagnostics-bridge.md) — Local vs deployed routing detail
- [monitoring.md](references/monitoring.md) — Telemetry inspection and export patterns
- [playwright-handoff.md](references/playwright-handoff.md) — Find the correct Aspire frontend URL before browser testing
AFrameArchitectureSample/.agents/skills/aspire-monitoring/references/diagnostics-bridge.md
+209
View File
@@ -0,0 +1,209 @@
# 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 |
AFrameArchitectureSample/.agents/skills/aspire-monitoring/references/monitoring.md
+161
View File
@@ -0,0 +1,161 @@
# Monitoring
Use this when the task is about inspecting app state, logs, traces, endpoints, or sharable diagnostics.
## Scenario: I Need To Know What Is Running And Where The Endpoints Are
Use these commands when the first job is to inspect current resource state, find URLs, or hand machine-readable app state to another tool.
```bash
aspire describe
aspire resources
aspire describe --apphost <path>
aspire describe --apphost <path> --format Json
```
Keep these points in mind:
- Use `aspire describe` first when you need the current state of the running app before deciding what to do next.
- Use `--apphost <path>` when the workspace has multiple AppHosts or discovery is ambiguous.
- Prefer `--format Json` when another tool or script needs to consume the result, such as a Playwright handoff or endpoint extraction.
## Scenario: Something Is Wrong, But Investigate Before Editing Code
Use these commands when the task is to diagnose behavior in the live app before making code changes.
```bash
aspire otel logs [resource] --format Json
aspire otel traces [resource] --format Json
aspire otel spans [resource] --format Json
aspire otel logs --trace-id <id> --format Json
aspire otel logs [resource] --search "connection timeout"
aspire otel spans [resource] --search "/api/products"
aspire logs [resource]
aspire logs [resource] --search "error"
```
Keep these points in mind:
- Prefer structured telemetry before raw console logs when possible.
- Use `aspire logs` as a secondary console-output view after checking structured telemetry.
- Use the trace-filtered log command when you already have a trace id and want the related log slice.
- Use `--search` to filter results by a case-insensitive text match across all fields (messages, attribute keys/values, trace/span IDs, resource names, severity, scope names). This is the fastest way to narrow output when you know what you're looking for.
- Prefer `--format Json` when another tool or script needs to consume the result, such as a Playwright handoff or endpoint extraction.
- `[resource]` is optional. Include it to filter results to a single resource; omit it to see all resources.
- `--search` can be combined with other options like `--format Json`, `--trace-id`, `--limit`, and resource filtering.
## Scenario: I Need A Sharable Diagnostics Bundle
Use this command when you need a portable handoff artifact for deeper analysis or for another person to inspect offline.
```bash
aspire export [resource]
```
Keep these points in mind:
- Use `aspire export` when you need a sharable bundle of telemetry and resource state.
- `[resource]` is optional. Include it to filter the export to a single resource; omit it to export all resources.
- The output is a zip archive (default name `aspire-export-<timestamp>.zip`) containing up to four directories:
- `resources/` — one JSON file per resource with resource details (name, type, state, endpoints, environment variables, etc.).
- `consolelogs/` — one plain-text file per resource with raw console output lines.
- `structuredlogs/` — one JSON file per resource with structured log entries in OTLP format.
- `traces/` — one JSON file per resource with distributed traces and spans in OTLP format.
- When extracting the export for analysis, look at `resources/` first for an overview, then drill into `consolelogs/`, `structuredlogs/` and `traces/` for detailed diagnostics.
## Dashboard Links
Commands like `aspire describe`, `aspire otel logs`, `aspire otel traces`, and `aspire otel spans` may include dashboard URLs in their JSON output. Only use URLs that are explicitly returned by these commands — do not construct dashboard URLs yourself.
When a dashboard link is returned alongside a resource or telemetry entry, make the resource name, trace ID, or span ID a clickable markdown link using the returned URL.
## Displaying Resources
When showing resource state to the user, display the state text with a circle emoji prefix:
- 🟢 Running, healthy
- 🟡 Starting, waiting
- 🔴 Failed, error, unhealthy
- ⚪ Stopped, exited
Link resource names to their dashboard page when the dashboard URL is known.
## Displaying Telemetry
When showing structured logs, prefix each entry with an emoji matching the log level:
- 🔴 Error / Critical
- 🟡 Warning
- 🔵 Information
- ⚪ Debug / Trace
Link resource names to their dashboard resource page. When trace IDs are present, display the first 7 characters and link that value to the full trace detail page.
When showing traces or spans, use 🟢 for success/unset status and 🔴 for error status. Display only the first 7 characters of trace and span IDs, and link those values to their dashboard detail pages.
## Production Monitoring Strategy (Azure)
Aspire auto-configures Application Insights when `AddAzureApplicationInsights()` is used in the AppHost. Deployed Azure apps export OpenTelemetry to App Insights automatically:
- Request traces and dependency tracking
- Exception logging
- Performance metrics
- Live Metrics stream
- Application Map (service topology)
No additional configuration is needed for Azure once the AppHost and deployment target wire the connection strings during deployment.
> **Docker Compose / Kubernetes**: Auto-configured App Insights does not apply. These targets require platform-native observability (Prometheus, Grafana, ELK, etc.) unless the app is explicitly configured to export OTEL to an external collector.
## Deployed App Monitoring — Route by Target
| Target | Tool | Commands |
|--------|------|----------|
| Azure Container Apps / App Service | azure-diagnostics | `az containerapp logs show`, `az webapp log tail`, App Insights |
| Azure resource health (Front Door, NSP, private endpoint, App Insights) | azure-diagnostics | AppLens, `az monitor app-insights query` |
| AKS workload (pods, workloads) | kubectl + Container Insights | `kubectl logs <pod>`, `kubectl describe pod <pod>`, Azure Monitor Container Insights |
| Docker / Compose | Docker CLI | `docker logs <container>`, `docker compose logs <service>` |
## Standalone Dashboard (`aspire dashboard run`)
`aspire dashboard run` launches the Aspire Dashboard without an AppHost, so any OTLP-emitting application can stream telemetry into it.
```bash
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 stopped. Agents must treat it as a long-running background process, 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:
```bash
aspire otel logs --dashboard-url "http://localhost:18888/login?t=TOKEN" --follow
aspire otel traces --dashboard-url "http://localhost:18888/login?t=TOKEN"
```
For dashboards configured with API-key authentication, pass `--api-key` alongside the base `--dashboard-url`:
```bash
aspire otel logs --dashboard-url https://my-dashboard.example.com --api-key "$DASHBOARD_API_KEY" --follow
```
## Browser Telemetry
Frontend resources opted into `Aspire.Hosting.Browsers` via `WithBrowserLogs()` surface browser console logs, network requests, and screenshots in the dashboard alongside server-side telemetry.
| 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 |
| Add `WithBrowserLogs()` to a resource | Route to `aspireify`; this is AppHost authoring, not monitoring |
## 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 such as azure-diagnostics, kubectl, or 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` and optional `--api-key`. This does not apply to `aspire logs` or `aspire describe`.
AFrameArchitectureSample/.agents/skills/aspire-monitoring/references/playwright-handoff.md
+21
View File
@@ -0,0 +1,21 @@
# Playwright Handoff
Use this when Playwright CLI is already configured and the next step is browser testing against a running Aspire app.
## Scenario: I Need The Right Frontend URL Before Browser Testing
Use these commands when the task is to discover the live frontend endpoint from Aspire state and then hand that URL to Playwright.
```bash
aspire describe --format Json
aspire describe --apphost <path> --format Json
playwright-cli --help
```
Keep these points in mind:
- Aspire discovers the endpoint first; Playwright uses the discovered endpoint after the handoff.
- Prefer `aspire describe --format Json` when the URL needs to be consumed by a script or passed to another tool.
- Use `--apphost <path>` when multiple AppHosts exist and the user is asking about one specific app.
- Do not guess frontend endpoints without first consulting Aspire state.
- If multiple frontends exist, use Aspire state to disambiguate which URL Playwright should use.