aspire-monitoring

Aspire 监控

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

诊断桥接 — 查看位置

需求	环境	工具	命令 / 路由
控制台日志	本地开发	Aspire CLI	aspire logs <resource>
结构化日志	本地开发	Aspire CLI	aspire otel logs [resource]
分布式追踪	本地开发	Aspire CLI	aspire otel traces [resource]
Span 详情	本地开发	Aspire CLI	aspire otel spans [resource]
正在运行的 AppHost	本地开发	Aspire CLI	aspire ps
资源状态	本地开发	Aspire CLI	aspire describe（如果缺少某个资源，请添加 --include-hidden）
遥测导出	本地开发	Aspire CLI	aspire export [resource]
独立仪表板	任意环境（无 AppHost）	Aspire CLI	aspire dashboard run（前台运行／阻塞式——见下文）
浏览器控制台 / 网络 / 诊断	本地开发（前端）	Aspire CLI + 仪表板	查找 <frontend>-browser-logs，启动其跟踪的浏览器，然后检查该浏览器的控制台日志
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 / Container Apps 日志	已部署到 Azure	azure-diagnostics	→ azure-diagnostics 技能
日志 / 状态	已部署到 Docker / Compose	Docker CLI	docker logs <container>、docker compose logs <service>

决策树：

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

详细路由说明请参阅 diagnostics-bridge.md。

调查工作流

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

1. aspire describe — 检查资源状态和终结点
2. aspire otel logs <resource> — 优先查看结构化日志
3. aspire logs <resource> — 将控制台输出作为辅助视图
4. aspire otel traces <resource> — 查看跨服务活动
5. aspire export — 导出压缩的遥测快照，以便深入分析

本地命令参考

命令	用途	示例
aspire logs <resource>	控制台 stdout/stderr	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 resources	用于查看资源状态的兼容性别名	新指南中优先使用 aspire describe
aspire export	可移植的遥测数据包	aspire export
aspire dashboard run	独立仪表板（前台运行／阻塞）	aspire dashboard run

默认情况下会过滤隐藏资源

aspire describe 和其他 CLI 命令会过滤掉 AppHost 中标记为隐藏的资源（代理、辅助容器、迁移）。默认输出适用于常规应用检查。在以下情况下添加 --include-hidden：

• 调试代理、边车／辅助容器或迁移作业。
• 预期资源在 aspire resources／aspire describe 中“缺失”。
• 排查可能涉及基础设施资源的连接或配置问题。

给 Agent 的提示

# ✅ 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/

特定版本的诊断

应用历史修复方法前，请检查正在运行的仪表板版本和实际错误。 旧版本中的修复并不能证明降级较新版本的仪表板可作为有效缓解措施， 即使只是暂时降级或在隔离测试中降级也是如此。

症状	指南
aspire describe 中缺少资源	重新运行 aspire describe --include-hidden；不要使用已移除的 aspire ps --include-hidden。
在 13.5.0-13.5.2 上，DevTunnel 运行正常但没有公共 URL	已在 13.5.3 中修复。请使用包含此修复的兼容版本，然后再更改端点配置。
在 13.5.0-13.5.2 上，已知的多路径图标会导致 Graph 崩溃	已在 13.5.3 中修复。请使用包含此修复的兼容版本。
在 13.5.3 或更高版本上，仪表板 Graph 崩溃	保持所选版本不变。请收集浏览器控制台堆栈跟踪和仪表板日志，以诊断其他原因或回归问题；不要建议安装 13.5.3 作为变通方法。

已在 13.3 中解决：针对 #16236 的独立仪表板变通方法已过时——请使用 aspire dashboard run（见下文）。

独立仪表板（aspire dashboard run）

aspire dashboard run 无需 AppHost 即可启动 Aspire Dashboard，因此任何发送 OTLP 的应用程序（无论是否使用 Aspire）都能向其流式传输遥测数据。

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

⚠️ 前台运行／阻塞。 aspire dashboard run 在停止它之前（Ctrl-C）不会返回。Agent 必须将其视为长期运行的后台进程——使用 bash 工具的 mode="async" 启动它，从初始输出中获取仪表板 URL 和令牌，并让它持续运行。不要将其作为一次性同步命令调用，也不要等待它“完成”。

将 Aspire CLI 连接到独立仪表板

aspire otel logs 和 aspire otel traces 支持 --dashboard-url。最简单的用法是传入 aspire dashboard run 打印的完整登录 URL——CLI 会自动规范化该 URL：

# 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"

对于配置了 API 密钥身份验证的仪表板（例如使用单独 API 密钥的独立容器映像），请在基础 --dashboard-url 旁传入 --api-key：

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

在 CLI 不可用的环境中，仍可使用容器映像版独立仪表板。

浏览器日志（Aspire.Hosting.Browsers）

当前端已选择启用 WithBrowserLogs() 时，Aspire 会创建一个名为 <frontend>-browser-logs 的子资源。浏览器控制台消息、错误、异常和网络诊断信息 会发送到该子资源的控制台日志流，而不是前端的 OpenTelemetry 日志。

1. 先查看常规的 aspire describe 或 aspire resources 输出，查找 <frontend>-browser-logs；aspire ps 不再列出资源。它是一个普通子资源，因此只有在找不到时才使用 aspire describe --include-hidden 重试。

2. 通过其父子关系和 Source 属性将其关联到前端。

3. 使用以下命令启动受跟踪的浏览器会话：

   aspire resource <frontend>-browser-logs open-tracked-browser
   

4. 使用以下命令检查浏览器诊断信息：

   aspire logs <frontend>-browser-logs
   

请勿使用 aspire otel logs <frontend> 获取浏览器输出；它不会返回该子资源的浏览器诊断信息。

需求	操作
检查现有浏览器诊断信息	查找 <frontend>-browser-logs，启动 open-tracked-browser，然后运行 aspire logs <frontend>-browser-logs
确认浏览器资源属于某个前端	检查子资源的父子关系和 Source 属性
确认前端已启用浏览器日志记录	检查 AppHost 中该资源是否配置了 .WithBrowserLogs()
为资源添加 WithBrowserLogs()	→ aspireify 技能（AppHost 编写）——请勿使用此技能编辑 AppHost

仪表板 UX 功能

检查运行中仪表板的 Agent 应了解以下内容：

• 通知中心（右上角的铃铛图标）——显示资源命令的结果和生命周期事件。内联命令响应会显示在此处，而不是从日志面板中抓取。
• 重建命令——适用于容器和项目资源；重建映像并重启资源，无需重启整个 AppHost。结果会显示在通知中心。
• 结构化命令结果——自定义资源命令会返回 ExecuteCommandResult，其中包含仪表板以内联方式呈现的 Message 负载；HTTP 命令可设置 HttpCommandResultMode.Auto | Json | Text | None，以控制响应正文的显示方式。
• 13.5 筛选——按时间戳筛选遥测数据，使用 == / != 精确匹配数值，并在流持续更新时搜索控制台日志文本。
• 终端视图——配置了实验性 WithTerminal() 的资源会在仪表板中以交互式会话形式打开。
• 没有仪表板 AI 助手——该功能已在 13.5 中移除。请改用 aspire agent init 和 AppHost/CLI Agent 集成。
• VS Code 启动需选择启用——Aspire 扩展不再自动打开仪表板。请使用其编辑器内仪表板，或配置 dashboardBrowser / launch.json。

编写自定义命令或添加 WithBrowserLogs() 调用属于 AppHost 工作——请转交给 aspireify。此技能用于观察这些功能在仪表板中的呈现内容。

为什么 Aspire CLI 无法执行远程诊断

Aspire CLI 通过 ~/.aspire/backchannels/ 下的本地反向通道套接字与正在运行的 AppHost 通信。这是有意如此——不存在远程反向通道。对于已部署的应用，请使用特定平台的工具（azure-diagnostics、kubectl、docker）。

例外：如果 Dashboard 可访问（与应用一同部署，或独立运行），aspire otel logs 和 aspire otel traces 可以通过 --dashboard-url（登录 URL 格式）以及可选的 --api-key 查询它（参见上文的独立 Dashboard 部分）。这不适用于 aspire logs 或 aspire describe。

转交规则

场景	转交至
启动／停止／等待／重建生命周期	→ 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

项目本地技能路由

如果 .agents/skills/aspire/SKILL.md 存在（由 aspire agent init 创建），请参阅其中的 references/monitoring.md，了解更深入的遥测工作流指南。

参考资料

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