遥测与 OpenTelemetry
更新: 2026-10-16 15:20:09 字数: 0 字 时长: 0 分钟
Aspire 的「可观测性层」这部分能力建立在 OpenTelemetry 之上。理解下面这条链路，就能理解 Aspire 里遥测是怎么流动的：
应用（OTel SDK） ──OTLP──► Aspire 仪表板（内存存储） ──► 仪表板 UI / Aspire CLI / MCP三个信号
| 信号 | 英文 | 说明 |
|---|---|---|
| 追踪 | Traces | 一次请求跨多个服务的完整调用链。 |
| 指标 | Metrics | 计数器、直方图等数值型度量。 |
| 日志 | Logs | 结构化日志，可与追踪关联。 |
应用侧：接入 OpenTelemetry
ASP.NET Core 项目通过 ServiceDefaults 一次性完成接入，无需在业务项目里重复配置：
builder.AddServiceDefaults();ConfigureOpenTelemetry 做了这些事：
- 注册 OpenTelemetry 的日志、指标、追踪。
- 为 ASP.NET Core、
HttpClient、运行时与运行时指标添加自动插桩。 - 根据环境变量决定导出目标。
非 .NET 服务怎么办？
Node.js、Python 等语言使用各自官方的 OpenTelemetry SDK，配置相同的 OTLP 端点即可，Aspire 会一并接收。详见独立运行仪表板。
环境变量
OpenTelemetry 有一套标准的已知环境变量。Aspire 项目启动时会自动设置其中最关键的几个：
OTEL_SERVICE_NAME=myfrontend
OTEL_RESOURCE_ATTRIBUTES=service.instance.id=1a5f9c1e-e5ba-451b-95ee-ced1ee89c168
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318| 变量 | 作用 |
|---|---|
OTEL_SERVICE_NAME | 服务名称，出现在仪表板与追踪中。 |
OTEL_RESOURCE_ATTRIBUTES | 资源属性，例如实例 ID。 |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP 导出端点，指向仪表板启动的 HTTP/2 端口。 |
这些变量在本地开发时自动注入，您通常不需要手工设置。
本地开发的工作流
用 F5 或 aspire run 启动项目时，发生的过程如下：
- 仪表板与 DCP 启动：Aspire 仪表板与开发控制平面（DCP）先启动。
- 执行 App 配置：AppHost 完成配置——
- 自动为 .NET 项目添加 OpenTelemetry 环境变量。
- DCP 为导出遥测提供
OTEL_SERVICE_NAME与OTEL_RESOURCE_ATTRIBUTES。 - OTLP 端点是仪表板启动的 HTTP/2 端口，写入
OTEL_EXPORTER_OTLP_ENDPOINT。 - 使用较短的导出间隔（
OTEL_BSP_SCHEDULE_DELAY、OTEL_BLRP_SCHEDULE_DELAY、OTEL_METRIC_EXPORT_INTERVAL），让数据尽快出现在仪表板上。
- 资源启动：DCP 启动配置好的项目、容器与可执行文件。
- 遥测流动：应用开始向仪表板发送遥测数据。
- 仪表板展示：仪表板近乎实时地显示所有 Aspire 项目的遥测。
以上步骤都是自动完成的，绝大多数情况下您只需要运行应用。
用 CLI 查询遥测
除了仪表板 UI，也可以用命令行检索同一批数据：
aspire otel logs # 结构化日志
aspire otel traces # 分布式追踪
aspire otel spans # 跨度明细
aspire export # 把遥测与资源数据打包为 zip加上 --format Json 可获得便于脚本处理的结构化输出。
为 AI 编码代理准备
AI 编码代理可以通过相同的数据诊断问题。典型工作流是：aspire start 启动 → aspire wait 等待资源 → 查询遥测定位问题 → 验证修复。这是对应用的观测，不是对代理推理过程或 Token 用量的监控。
导出到其他后端
本地开发默认导出到仪表板。如果想同时送到 Seq、Grafana、Jaeger 等平台，可以在 AppHost 中声明对应的集成并让服务引用它：
var seq = builder.AddSeq("seq");
builder.AddProject<Projects.Api>("api")
.WithReference(seq);被引用的可观测性资源会通过服务发现把 OTLP 端点注入到服务中。
部署后的遥测
部署环境应当配置符合自身情况的 OpenTelemetry 环境变量，例如把 OTEL_EXPORTER_OTLP_ENDPOINT 指向该环境的 OTLP 收集器或监控服务。
未配置就不导出
如果没有配置 OTEL_EXPORTER_OTLP_ENDPOINT，OTLP 导出会被禁用。
部署完成后，如果希望继续观察，可以把应用的遥测指向一个独立运行的仪表板实例，详见独立运行仪表板。
