Wegent可观测性搭建教程:用OpenTelemetry追踪你的AI任务全链路
Wegent可观测性搭建教程:用OpenTelemetry追踪你的AI任务全链路
Wegent 是一款开源、可自托管的 AI 工作空间,支持编码、协作与自动化任务执行。当 AI 任务跨越多服务(backend、executor-manager 等)执行时,排查"任务为什么慢/失败"往往困难重重。本教程带你用 OpenTelemetry 快速搭建 Wegent 内置的可观测性栈,一键追踪 AI 任务从 API 请求、数据库查询到模型调用的全链路 Trace,并学会在 Jaeger 中阅读调用链、在生产环境调优采样与降噪参数。
为什么需要 AI 任务全链路追踪?
在 Wegent 中,一个 AI 任务的执行通常要穿越多个服务:
- HTTP 请求进入
wegent-backend - SQLAlchemy 读写数据库
- Redis 缓存与队列操作
- HTTP 客户端(httpx / requests)调用模型与外部服务
如果只靠日志,跨服务拼接耗时和错误上下文非常低效。Wegent 基于 OpenTelemetry 的 Trace 机制,将同一次任务产生的所有操作串成一条调用链——每个 Span 自带 task_id、user_id、model.name 等业务属性,一眼定位瓶颈。
架构总览:4 个组件各司其职
Wegent 在 docker/telemetry/ 目录下内置了一整套开箱即用的可观测性基础设施:
| 服务 | 端口 | 地址 | 作用 |
|---|---|---|---|
| Jaeger | 16686 | http://localhost:16686 | 链路可视化与依赖图(推荐入口) |
| Kibana | 5601 | http://localhost:5601 | 复杂查询与仪表盘 |
| Elasticsearch | 9200 | http://localhost:9200 | 链路/日志的长期存储 |
| OTel Collector | 4317 / 4318 | - | 采集与转发遥测数据(OTLP gRPC / HTTP) |
数据流向:应用服务 →(OTLP)→ OTel Collector →(双写)→ Jaeger + Elasticsearch。Collector 配置见 otel-collector-config.yaml,其中已内置批量导出、内存保护(memory_limiter)以及健康检查、静态资源等噪声 Span 的过滤规则。
多 Agent 协作场景下(如团队中多个 Bot 串联执行 Pipeline),链路追踪尤其有价值——每个 Bot 的调用都会作为子 Span 挂在任务主链路上:
快速搭建:三步启动可观测性栈
第一步:先启动主服务
在项目根目录启动 Wegent 主服务(用于创建共享网络):
docker-compose up -d
第二步:启动可观测性栈
# 进入遥测目录
cd docker/telemetry
docker-compose up -d
# 或从项目根目录直接指定配置文件
docker-compose -f docker/telemetry/docker-compose.yml up -d
Compose 配置位于 docker/telemetry/docker-compose.yml,包含 Elasticsearch(单节点模式)、Kibana、Jaeger all-in-one 以及 OTel Collector 四个服务。
第三步:为服务开启 OTEL
本地开发:设置环境变量后启动 backend 即可:
OTEL_ENABLED=true \
OTEL_SERVICE_NAME=wegent-backend \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
./start.sh
Docker 部署:在主 docker-compose.yml 中各服务(backend、chat-shell、executor-manager、knowledge-runtime)均已预留了 OTEL 环境变量注释段,按需取消注释并改为:
environment:
OTEL_ENABLED: "true"
OTEL_SERVICE_NAME: "wegent-backend"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
💡 注意:Docker 网络内部请指向
otel-collector:4317,本地直连才用localhost:4317。
服务内部:trace 是如何产生的?
Wegent 的埋点代码集中在 shared/telemetry/ 模块,被 backend、executor、executor-manager 等服务共享:
- 统一配置:shared/telemetry/config.py 从环境变量读取全部 OTEL 配置(开关、采样率、URL 黑白名单、请求体捕获等),是所有服务的唯一配置来源;
- 初始化入口:shared/telemetry/core.py 提供
init_telemetry(),backend 在启动流程中调用它完成 Tracer/Meter 初始化,见 backend/app/main.py; - 自动埋点:shared/telemetry/instrumentation.py 一键为 FastAPI、SQLAlchemy、Redis、HTTPX、Requests 及系统指标(CPU/内存)打点,并针对 SSE 流式接口自动关闭
http.send/http.receive内部 Span 以避免噪声爆炸; - 业务 Span:shared/telemetry/context/manager.py 的
SpanManager封装了任务级埋点,自动附加task_id、user_id、model.name、model.provider等属性,并在异常时记录详细错误上下文; - 业务指标:shared/telemetry/metrics/business.py 预定义了会话、消息、任务、模型调用等计数器与直方图,开启
OTEL_METRICS_ENABLED=true后即可导出。
也就是说,你几乎不需要手写埋点代码,只要环境变量配置正确,链路数据就会自动产生。
在 Jaeger 中查看 AI 任务全链路
- 打开 http://localhost:16686;
- 在 Service 下拉框选择
wegent-backend(或其他服务名); - 点击 Find Traces;
- 点击任意一条 Trace,即可展开完整调用链:HTTP 入口 Span → 数据库 Span → 模型调用 Span,以及每一段的耗时。
需要复杂检索(如按错误状态过滤、按任务聚合)时,可改用 Kibana:打开 http://localhost:5601,在 Stack Management → Data Views 中为 otel-traces* 创建数据视图,然后在 Discover 中查询。
生产环境关键参数调优
| 环境变量 | 说明 | 默认值 |
|---|---|---|
OTEL_ENABLED |
总开关 | false |
OTEL_SERVICE_NAME |
服务名(区分链路来源) | wegent-service |
OTEL_EXPORTER_OTLP_ENDPOINT |
OTLP 上报地址 | http://otel-collector:4317 |
OTEL_TRACES_SAMPLER_ARG |
采样率(0.0-1.0),生产建议 0.1 | 1.0 |
OTEL_METRICS_ENABLED |
是否导出指标 | false |
OTEL_EXCLUDED_URLS |
URL 黑名单(逗号分隔) | health、metrics、docs 等 |
OTEL_INCLUDED_URLS |
URL 白名单模式(设置后忽略黑名单) | 空(全量) |
OTEL_CAPTURE_REQUEST_BODY |
捕获请求体(慎用,注意隐私) | false |
OTEL_MAX_BODY_SIZE |
请求体捕获上限(字节) | 4096 |
🔍 降噪小技巧:默认配置已排除心跳、健康检查、OpenAPI 文档等高频低价值请求;如果某个高频接口仍然刷屏,把它加进 OTEL_EXCLUDED_URLS 即可。
验证与常见问题
确认数据是否落库(查看 Elasticsearch 中的 otel 索引):
curl http://localhost:9200/_cat/indices?v | grep otel
测试 OTLP 端点是否可达:
curl -v http://localhost:4318/v1/traces
查看 Collector 日志:
docker-compose -f docker/telemetry/docker-compose.yml logs -f otel-collector
| 现象 | 排查方向 |
|---|---|
| Jaeger 查不到数据 | 检查服务容器内 OTEL_EXPORTER_OTLP_ENDPOINT 是否指向 otel-collector:4317 |
| Elasticsearch 无索引 | 确认 backend 启动日志出现 "OpenTelemetry initialized successfully" |
| Span 过多 | 调低 OTEL_TRACES_SAMPLER_ARG,或扩展 URL 黑名单 |
停止整个可观测性栈:
cd docker/telemetry
docker-compose down # 保留数据
docker-compose down -v # 连同数据卷一起删除
写在最后
Wegent 将 OpenTelemetry 的可观测性栈做成了"改几个环境变量就能跑"的体验:docker/telemetry/README.md 中有完整的组件说明与架构图,docker/telemetry/docker-compose.yml 提供一键部署,shared/telemetry/ 则负责让每个服务"自动上报"。按本教程三步走,你就能看到自己的 AI 任务在 Jaeger 中从请求到结果的全链路,让排查与调优从此有据可依 🚀


