aspire-monitoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Aspire Monitoring

Aspire 监控

Aspire CLI provides full observability locally. For deployed apps, route to platform-specific tools.

Aspire CLI 提供完整的本地可观测能力。对于已部署的应用，请使用平台专属工具。

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:

Is this about AppHost code or deployment definition? →
```
aspire-deployment
```
skill.
Is the app running locally via
```
aspire start
```
? → Aspire CLI.
Is it deployed to AKS? → kubectl + Container Insights for workload;
```
azure-diagnostics
```
for the cluster's Azure resources.
Is it deployed to other Azure (App Service, Container Apps)? →
```
azure-diagnostics
```
.
Is it deployed to Docker / Compose? →
```
docker
```
/
```
docker compose
```
CLI.

See diagnostics-bridge.md for detailed routing.

需求	环境	工具	命令/路由
控制台日志	本地开发	Aspire CLI	`aspire logs <resource>`
结构化日志	本地开发	Aspire CLI	`aspire otel logs [resource]`
分布式追踪	本地开发	Aspire CLI	`aspire otel traces [resource]`
Span 详情	本地开发	Aspire CLI	`aspire otel spans [resource]`
资源状态	本地开发	Aspire CLI	`aspire describe` （若资源缺失，添加 `--include-hidden` ）
遥测导出	本地开发	Aspire CLI	`aspire export [resource]`
独立仪表板	任意环境（无需AppHost）	Aspire CLI	`aspire dashboard run` （前台/阻塞模式——详见下文）
浏览器控制台/网络/截图	本地开发（前端）	Aspire仪表板	通过 `Aspire.Hosting.Browsers` + `WithBrowserLogs()` 展示
AppHost/部署定义	开发阶段	aspire-deployment技能	→ `aspire-deployment` 技能
AKS工作负载（Pod日志、Pod状态）	已部署至AKS	kubectl + Container Insights	`kubectl logs <pod>` 、 `kubectl describe pod <pod>` 、Azure Monitor中的Container Insights
Azure资源健康状态（App Insights、Front Door、NSP、专用端点）	已部署至Azure	azure-diagnostics	→ `azure-diagnostics` 技能
App Service/容器应用日志	已部署至Azure	azure-diagnostics	→ `azure-diagnostics` 技能
日志/状态	已部署至Docker/Compose	Docker CLI	`docker logs <container>` 、 `docker compose logs <service>`

决策树：

是否涉及AppHost代码或部署定义？ →
```
aspire-deployment
```
技能。
应用是否通过
```
aspire start
```
在本地运行？ → 使用Aspire CLI。
是否已部署至AKS？ → 工作负载使用kubectl + Container Insights；集群Azure资源使用
```
azure-diagnostics
```
。
是否已部署至其他Azure服务（App Service、容器应用）？ →
```
azure-diagnostics
```
。
是否已部署至Docker/Compose？ →
```
docker
```
/
```
docker compose
```
CLI。

查看diagnostics-bridge.md获取详细路由说明。

Investigation Workflow

排查流程

When something is wrong, investigate before editing code:

```
aspire describe
```
— check resource state and endpoints
```
aspire otel logs <resource>
```
— structured logs first
```
aspire logs <resource>
```
— console output as secondary view
```
aspire otel traces <resource>
```
— cross-service activity
```
aspire export
```
— zipped telemetry snapshot for deeper analysis

出现问题时，请先排查再修改代码：

```
aspire describe
```
—— 检查资源状态和端点
```
aspire otel logs <resource>
```
—— 优先查看结构化日志
```
aspire logs <resource>
```
—— 次要查看控制台输出
```
aspire otel traces <resource>
```
—— 跨服务活动追踪
```
aspire export
```
—— 导出遥测快照包以进行深度分析

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`

命令	用途	示例
`aspire logs <resource>`	控制台标准输出/错误输出	`aspire logs apiservice`
`aspire logs --follow`	实时流式输出日志	`aspire logs apiservice --follow`
`aspire otel logs`	结构化OpenTelemetry日志	`aspire otel logs`
`aspire otel traces`	分布式追踪数据	`aspire otel traces`
`aspire otel spans`	单个Span详情	`aspire otel spans`
`aspire otel logs --trace-id <id>`	与指定追踪关联的日志（⚠️ 请验证参数）	`aspire otel logs --trace-id abc123`
`aspire otel logs --dashboard-url`	查询独立仪表板（登录URL或基础URL + `--api-key` ）	`aspire otel logs --dashboard-url "http://localhost:18888/login?t=TOKEN" --follow`
`aspire otel traces --dashboard-url`	查询独立仪表板	`aspire otel traces --dashboard-url "http://localhost:18888/login?t=TOKEN"`
`aspire describe`	资源状态、端点、健康状况	`aspire describe --format Json`
`aspire describe --include-hidden`	包含代理、辅助容器、迁移任务	`aspire describe --include-hidden --format Json`
`aspire ps --format Json`	带状态的资源列表（已过滤）	`aspire ps --format Json`
`aspire ps --include-hidden --format Json`	包含隐藏资源的列表	`aspire ps --include-hidden --format Json`
`aspire export`	可移植遥测包	`aspire export`
`aspire dashboard run`	独立仪表板（前台/阻塞模式）	`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.

aspire ps

、

aspire describe

及其他CLI命令会过滤掉AppHost中标记为隐藏的资源（代理、辅助容器、迁移任务）。默认输出适用于常规应用检查。在以下场景添加

--include-hidden

：

调试代理、边车/辅助容器或迁移任务时。
预期资源未出现在
```
aspire ps
```
/
```
aspire describe
```
中时。
排查可能涉及基础设施资源的连接或配置问题时。

Tips for Agents

面向Agent的技巧

bash

undefined

bash

undefined

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

✅ 使用--format Json以支持机器解析（支持命令：ps、describe、start）

aspire describe --format Json

✅ When a resource you expect is missing, retry with --include-hidden

✅ 若预期资源缺失，添加--include-hidden重试

aspire ps --include-hidden --format Json | jq '.[] | {name, displayName, state, hidden}'

✅ Get endpoints from describe, not guessing ports

✅ 从describe命令获取端点，而非猜测端口

ENDPOINT=$(aspire describe apiservice --format Json | jq -r '.endpoints[0].url')

✅ Use --apphost <path> when multiple AppHosts exist

✅ 存在多个AppHost时使用--apphost <路径>

aspire describe --apphost ./src/MyApp.AppHost/

undefined

aspire describe --apphost ./src/MyApp.AppHost/

undefined

Known Diagnostics Issues

已知诊断问题

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

问题	症状	解决方法
TS AppHost DNS失败(#15782)	`aspire otel` 提示 `*.dev.localhost` "无此主机"	使用 `--dashboard-url localhost:PORT`
`--isolated` 模式遥测(#16107)	隔离模式下OTEL端口未随机化	若需要遥测功能，请避免使用 `--isolated`
资源未出现在 `aspire ps` / `aspire describe` 中	默认隐藏的资源（如代理、辅助工具或迁移任务）	添加 `--include-hidden` 重新运行命令

13.3版本已修复：#16236的独立仪表板解决方法已过时——请使用
aspire dashboard run
（详见下文）。

Standalone Dashboard (

aspire dashboard run

)

独立仪表板(

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

aspire dashboard run

无需AppHost即可启动Aspire仪表板，因此任何支持OTLP输出的应用（无论是否基于Aspire）都可将遥测数据流式传输至其中。

bash

aspire dashboard run

Dashboard: http://localhost:18888/login?t=<TOKEN>

仪表板地址: 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".


> ⚠️ **前台/阻塞模式**。`aspire dashboard run`会持续运行直到手动停止（Ctrl-C）。Agent需将其视为长期运行的后台进程——使用bash工具的`mode="async"`启动，从初始输出中捕获仪表板URL和令牌，并保持其运行。**请勿**将其作为单次同步命令调用，也**请勿**等待其"完成"。

Connect the Aspire CLI to a standalone dashboard

将Aspire CLI连接至独立仪表板

aspire otel logs

and

aspire otel traces

--dashboard-url

. The simplest form passes the full login URL printed by

aspire dashboard run

— the CLI normalizes it automatically:

bash

undefined

aspire otel logs

和

aspire otel traces

支持

--dashboard-url

参数。最简单的方式是传入

aspire dashboard run

输出的完整登录URL——CLI会自动标准化处理：

bash

undefined

Stream structured logs from a standalone dashboard (login URL form)

从独立仪表板流式输出结构化日志（登录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 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.

aspire otel traces --dashboard-url "http://localhost:18888/login?t=TOKEN"


对于配置了API密钥认证的仪表板（例如独立容器镜像搭配单独的API密钥），请在`--dashboard-url`基础上添加`--api-key`参数：

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

独立容器镜像仪表板仍适用于无法使用CLI的环境。

Browser Telemetry (

Aspire.Hosting.Browsers

)

浏览器遥测(

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.

Aspire.Hosting.Browsers

集成可在本地开发期间捕获前端资源的浏览器控制台日志、网络请求和截图，并将其与服务器端遥测一起展示在仪表板中。前端资源需通过

WithBrowserLogs()

选择启用该功能。

需求	操作
查看已配置的浏览器遥测	打开仪表板；浏览器日志/网络/截图会与对应资源的服务器遥测一同展示
确认前端是否已启用该功能	检查AppHost中资源是否配置了 `.WithBrowserLogs()` （例如 `AddViteApp("frontend").WithBrowserLogs()` ）
为资源添加 `WithBrowserLogs()`	→ `aspireify` 技能（AppHost开发）——请勿通过本技能编辑AppHost

以编程方式解析遥测数据时，浏览器日志会作为关联前端资源的额外OTLP日志记录返回——

aspire otel logs <frontend-resource>

会将其与服务器日志一同返回。

Dashboard UX Features

仪表板UX功能

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.

查看运行中仪表板的Agent需了解以下功能：

通知中心（右上角铃铛图标）——展示资源命令和生命周期事件的结果。命令的内联响应会显示在此处，而非从日志面板抓取。
重建命令——容器和项目资源可用；重新构建镜像并重启资源，无需重启整个AppHost。结果会显示在通知中心。
结构化命令结果——自定义资源命令返回
```
ExecuteCommandResult
```
，其中包含
```
Message
```
负载，仪表板会内联渲染；HTTP命令可设置
```
HttpCommandResultMode.Auto | Json | Text | None
```
以控制响应体的展示方式。

自定义命令或
WithBrowserLogs()
调用的开发属于AppHost工作范畴——请路由至**
aspireify
**技能。本技能仅用于观测这些功能在仪表板中展示的内容。

Why Aspire CLI Can't Do Remote Diagnostics

为何Aspire CLI无法进行远程诊断

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

aspire describe

Aspire CLI通过本地回传套接字

~/.aspire/backchannels/

与运行中的AppHost通信。这是设计使然——不存在远程回传机制。对于已部署的应用，请使用平台专属工具（azure-diagnostics、kubectl、docker）。

例外情况：若仪表板可访问（与应用一同部署或独立运行），

aspire otel logs

和

aspire otel traces

可通过

--dashboard-url

（登录URL格式）和可选的

--api-key

进行查询（详见上文独立仪表板部分）。此方式不适用于

aspire logs

或

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`

场景	转接至
启动/停止/等待/重建生命周期	→ `aspire-orchestration` 技能
部署、发布、流水线步骤、AppHost计算环境绑定	→ `aspire-deployment` 技能
AppHost代码修改（ `WithBrowserLogs()` 、自定义命令、 `WithHttpCommand` ）	→ `aspireify` 技能
已部署Azure资源健康状态（App Insights、Front Door、NSP、专用端点、ACA、App Service）	→ `azure-diagnostics` 技能（azure-skills）
AKS工作负载诊断（Pod日志、Pod状态、Container Insights）	→ `kubectl` + Azure Monitor Container Insights
Docker/Compose容器日志	→ `docker logs` / `docker compose logs`

Project-Local Skill Routing

项目本地技能路由

.agents/skills/aspire/SKILL.md

exists (from

aspire agent init

), see its

references/monitoring.md

for deeper telemetry workflow guidance.

若存在

.agents/skills/aspire/SKILL.md

（来自

aspire agent init

），请查看其

references/monitoring.md

获取更深入的遥测流程指导。

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

diagnostics-bridge.md —— 本地与已部署环境的路由详情
monitoring.md —— 遥测检查与导出模式
playwright-handoff.md —— 浏览器测试前获取正确的Aspire前端URL

aspire-monitoring

Original

Translation

Aspire Monitoring

Aspire 监控

Diagnostics Bridge — Where To Look

诊断桥接——该查看哪里

Investigation Workflow

排查流程

Local Commands Reference

本地命令参考

Hidden resources are filtered by default

默认隐藏资源会被过滤

Tips for Agents

面向Agent的技巧

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

✅ 使用--format Json以支持机器解析（支持命令：ps、describe、start）

✅ When a resource you expect is missing, retry with --include-hidden

✅ 若预期资源缺失，添加--include-hidden重试

✅ Get endpoints from describe, not guessing ports

✅ 从describe命令获取端点，而非猜测端口

✅ Use --apphost <path> when multiple AppHosts exist

✅ 存在多个AppHost时使用--apphost <路径>

Known Diagnostics Issues

已知诊断问题

Standalone Dashboard (aspire dashboard run)

独立仪表板(aspire dashboard run)

Dashboard: http://localhost:18888/login?t=<TOKEN>

仪表板地址: http://localhost:18888/login?t=<TOKEN>

OTLP/gRPC: http://localhost:4317

OTLP/gRPC: http://localhost:4317

OTLP/HTTP: http://localhost:4318

OTLP/HTTP: http://localhost:4318

Connect the Aspire CLI to a standalone dashboard

将Aspire CLI连接至独立仪表板

Stream structured logs from a standalone dashboard (login URL form)

从独立仪表板流式输出结构化日志（登录URL格式）

Search recent traces

搜索近期追踪数据

Browser Telemetry (Aspire.Hosting.Browsers)

浏览器遥测(Aspire.Hosting.Browsers)

Dashboard UX Features

仪表板UX功能

Why Aspire CLI Can't Do Remote Diagnostics

为何Aspire CLI无法进行远程诊断

Handoff Rules

转接规则

Project-Local Skill Routing

项目本地技能路由

References

参考资料

Standalone Dashboard (
`aspire dashboard run`
)

独立仪表板(
`aspire dashboard run`
)

Browser Telemetry (
`Aspire.Hosting.Browsers`
)

浏览器遥测(
`Aspire.Hosting.Browsers`
)