Wegent可观测性搭建教程:用OpenTelemetry追踪你的AI任务全链路

原创2026-10-25 15:24:08855 阅读

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 等业务属性,一眼定位瓶颈。

Wegent Web 中向 AI 发起任务,每个任务都会在可观测性栈中生成一条完整调用链

架构总览: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 多 Bot 团队协作配置界面,每个 Agent 的调用都会体现在同一条链路中

快速搭建:三步启动可观测性栈

第一步:先启动主服务

在项目根目录启动 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 任务全链路

  1. 打开 http://localhost:16686;
  2. 在 Service 下拉框选择 wegent-backend(或其他服务名);
  3. 点击 Find Traces;
  4. 点击任意一条 Trace,即可展开完整调用链:HTTP 入口 Span → 数据库 Span → 模型调用 Span,以及每一段的耗时。

Wegent 工作空间任务视图,任务执行状态可与 Trace 数据相互印证

需要复杂检索(如按错误状态过滤、按任务聚合)时,可改用 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 中从请求到结果的全链路,让排查与调优从此有据可依 🚀

登录后查看全文
Wegent