TaskWeaver 遥测(Telemetry)实战指南:基于 OpenTelemetry 的追踪、指标与性能瓶颈分析
TaskWeaver 遥测(Telemetry)实战指南:基于 OpenTelemetry 的追踪、指标与性能瓶颈分析
TaskWeaver 作为面向数据分析任务的 code-first Agent 框架,其执行链路横跨 Planner、CodeGenerator、CodeExecutor 等多个角色与模块。本文围绕官方文档 telemetry.md 展开,完整讲解如何借助 OpenTelemetry 为 TaskWeaver 启用分布式追踪(Tracing)与指标(Metrics)采集,覆盖启用配置、基础设施搭建、Jaeger/Prometheus 可视化查询,以及基于 taskweaver/module/tracing.py 的源码级自定义扩展。读完本文,你将能够在自己的 TaskWeaver 项目中复现一套可观测体系,精确定位一次数据分析任务的耗时瓶颈、Token 消耗与错误来源。
上图展示了一个典型任务(分析一个上传的文件)的追踪时间线。可以看到任务执行被划分为三个主要阶段:
- 规划阶段(Planning):Planner 决定需要执行的子任务;
- 代码生成与执行阶段(Code generation & execution):CodeGenerator 生成代码,CodeExecutor 执行代码;
- 回复阶段(Reply):Planner 将回复发送给用户。
时间线中带有黑色描边的条代表任务执行的关键路径(critical path),即贯穿整个任务的最长路径,它是定位执行瓶颈的最直接依据。从默认场景的追踪结果可以清楚看到:当前任务的执行时间主要被对 LLM 的调用所主导。
一、TaskWeaver 能追踪哪些内容
启用 Telemetry 后,OpenTelemetry 的埋点会覆盖以下五类信息:
- 角色间交互:Planner、CodeInterpreter 与 Executor 之间的消息流转;
- 各角色与核心组件的耗时:每个角色及主要模块消耗的时间;
- LLM 的 Prompt 与响应:发送给 LLM 的 Prompt 原文与收到的响应;
- 任务状态与错误:任务的执行状态(OK/ERROR)以及遇到的异常;
- Token 消耗:每个角色消耗的 Token 数量。
点击任意一个 span(追踪中的最小工作单元),可以查看该 span 的详细属性与日志。以下截图展示了 Planner 回复函数的 span 详情:
从该视图中可以看到用户查询(user_query)、发送给 LLM 的 Prompt 原文,以及 LLM 消耗的 Token 数(prompt_size 与 output_size)。除此之外,生成的代码、不同角色之间传递的 post 消息等关键数据也被记录在追踪中。
追踪还提供多种视图,例如调用图视图(call graph),用于展示 span 之间的调用层级关系,方便从整体上把握一次任务的调用树结构。
二、如何启用 Tracing
1. 安装 OpenTelemetry 依赖
Tracing 默认处于关闭状态。要启用它,首先需要安装 OpenTelemetry 所需的 Python 包。核心依赖包括:
opentelemetry-api:OpenTelemetry 的 API 层;opentelemetry-sdk:OpenTelemetry 的 SDK 实现;opentelemetry-exporter-otlp:OTLP 协议导出器,用于将数据发送到 Collector;opentelemetry-instrumentation:自动埋点工具包;tiktoken:用于统计任务执行过程中的 Token 消耗。
其中 tiktoken 是统计 Token 消耗所必需的依赖。需要注意的是,当前实现仅支持 OpenAI 系列模型的 tokenizer,其他模型暂不支持 Token 计数。
如果缺少上述依赖,Tracing 类的初始化逻辑 会抛出 ImportError,提示先安装 opentelemetry-sdk、opentelemetry-api、opentelemetry-exporter-otlp、opentelemetry-instrumentation 与 tiktoken。
2. 修改项目配置文件
安装完成后,在项目配置文件(如 project/taskweaver_config.json)中设置 tracing.enabled=true 即可开启追踪。一个典型的 Tracing 配置如下:
{
"tracing.enabled": true,
"tracing.exporter": "otlp",
"tracing.endpoint": "http://127.0.0.1:4317",
"tracing.tokenizer_target_model": "gpt-4"
}
3. Tracing 全部配置项与默认值
结合 taskweaver/module/tracing.py 中 TracingConfig 的源码实现,tracing 模块支持的全部配置项如下:
| 配置项 | 默认值 | 说明 |
|---|---|---|
tracing.enabled |
false |
是否启用 Tracing,默认关闭 |
tracing.endpoint |
http://127.0.0.1:4317 |
OpenTelemetry Collector 的 gRPC 接收地址 |
tracing.service_name |
taskweaver.otlp.tracer |
上报时使用的服务名(Service Name),会作为资源属性写入 trace 与 metric |
tracing.exporter |
otlp |
导出器类型,支持 otlp(OTLP gRPC 导出)与 console(控制台输出,用于本地调试) |
tracing.tokenizer_target_model |
gpt-4 |
用于 Token 计数的目标模型,需为 tiktoken 支持的 OpenAI 模型 |
tokenizer_target_model 的默认值是 gpt-4。若你的 LLM 使用其他模型,可显式设置该配置项指向对应的 tiktoken 编码;Tracing.__init__ 中通过 tiktoken.encoding_for_model(...) 加载对应编码器(见 taskweaver/module/tracing.py)。可用的模型列表以 tiktoken 包内置的模型表为准。
三、搭建追踪基础设施(Docker Compose 一键启动)
官方文档强调,下文搭建的是一个玩具级(toy)追踪系统:数据不会持久化,仅用于功能验证与演示。生产环境需要部署更健壮的存储与后端。TaskWeaver 代码中的埋点会先将 traces 与 metrics 发送到 OpenTelemetry Collector;Collector 负责接收、处理后,再分别导出到 Jaeger(追踪后端)与 Prometheus(指标后端)。
基础设施所需的编排文件位于仓库的 tracing 目录下(文档正文中提到的 /TaskWeaver/tracing_configure/ 路径为笔误,实际文件就在 tracing/ 目录中)。启动命令如下:
cd /TaskWeaver/tracing
docker-compose up
启动后会看到大量容器日志,请留意其中是否有错误。一切正常后,即可访问:
- Prometheus 前端:
http://localhost:9090 - Jaeger 前端:
http://localhost:16686
该编排默认假设容器与 TaskWeaver 运行在同一台机器上。若 TaskWeaver 与容器不在同一主机,需要通过项目配置中的 tracing.endpoint 将导出地址指向 Collector 所在主机的地址。
1. docker-compose.yaml 详解
tracing/docker-compose.yaml 定义了三个服务:
version: '3'
services:
optl-collector:
image: otel/opentelemetry-collector:0.96.0
command: ["--config=/etc/collector-config.yaml"]
volumes:
- ./collector-config.yaml:/etc/collector-config.yaml
ports:
- "4317:4317" # Expose the gRPC receiver port for the collector
depends_on:
- jaeger
jaeger:
image: jaegertracing/all-in-one:1.54
ports:
- "16686:16686" # Jaeger UI
prometheus:
image: prom/prometheus:latest
ports:
- "9090:9090" # Prometheus UI
volumes:
- ./prometheus-config.yml:/etc/prometheus/prometheus.yml
command: ["--config.file=/etc/prometheus/prometheus.yml"]
depends_on:
- optl-collector
要点:
- Collector 镜像使用
otel/opentelemetry-collector:0.96.0,仅暴露 gRPC 接收端口4317(对应 TaskWeaver 侧tracing.endpoint的默认地址); - Collector 的配置通过 volume 将宿主机的 tracing/collector-config.yaml 挂载进容器;
- Jaeger 使用
all-in-one单机镜像,UI 端口16686; - Prometheus 通过挂载 tracing/prometheus-config.yml 作为抓取配置,UI 端口
9090。
2. collector-config.yaml 详解
tracing/collector-config.yaml 定义了接收器、导出器与流水线:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
exporters:
debug:
verbosity: detailed
otlp:
endpoint: "jaeger:4317"
tls:
insecure: true
prometheus:
endpoint: "0.0.0.0:9464"
service:
pipelines:
traces:
receivers: [otlp]
exporters: [otlp]
metrics:
receivers: [otlp]
exporters: [prometheus]
logs:
receivers: [otlp]
exporters: [debug]
配置要点:
- 接收器(receivers):OTLP 协议同时开启 gRPC(
0.0.0.0:4317)与 HTTP(0.0.0.0:4318)两个接收端点; - 导出器(exporters):
debug导出器以detailed级别输出日志,用于排查问题;otlp导出器指向jaeger:4317——由于 Jaeger 兼容 OpenTelemetry Collector 的导出协议,可直接将 traces 转发给 Jaeger,并通过tls.insecure: true关闭 TLS;prometheus导出器在0.0.0.0:9464端口暴露 Prometheus 可抓取的指标端点;
- 流水线(pipelines):traces 走
otlp → otlp(到 Jaeger),metrics 走otlp → prometheus,logs 走otlp → debug。
3. prometheus-config.yml 详解
tracing/prometheus-config.yml 只抓取 Collector 暴露的指标:
scrape_configs:
- job_name: optl-collector
scrape_interval: 5s
static_configs:
- targets: ["optl-collector:9464"]
即每 5 秒从 optl-collector:9464 拉取一次指标。
四、如何查看 Metrics(指标)
上一节已说明如何在 Jaeger 前端查看 traces。查看 Prometheus 指标则相对复杂,因为每个指标都是一条时间序列(time series)——即一串带时间戳的数据点。OpenTelemetry 允许为指标附加属性(attributes),从而支持按属性过滤。
当前实现中只注册了一个指标 prompt_size,用于记录发送给 LLM 的 Prompt 大小(见 taskweaver/module/tracing.py,该计数器在初始化时通过 Meter.create_counter("prompt_size", unit="1", ...) 创建)。在 Prometheus 中可以看到对应的时间序列 prompt_size_total——它是所有 trace 累计的 Prompt 大小,单调递增。
指标上目前只标注了一个属性 direction,取值为 input 或 output,分别表示"输入 Prompt 的大小"与"LLM 响应输出的大小"。
在 Prometheus 前端使用 PromQL 查询语言即可检索指标。上图的查询语句为:
increase(prompt_size_total[10m])
其含义是:展示最近 10 分钟滑动窗口内 Token 消耗的增量。
若希望用 Grafana 可视化这些指标,可自行部署一个 Grafana 实例并将 Prometheus 配置为数据源。在 docker-compose.yaml 中追加以下内容即可在现有编排中附带 Grafana:
grafana:
image: grafana/grafana-enterprise:latest
ports:
- "3000:3000" # Grafana UI
environment:
- GF_SECURITY_ADMIN_PASSWORD=secret # You should change 'secret' to a password of your choosing
- GF_USERS_ALLOW_SIGN_UP=false
volumes:
- grafana_data:/var/lib/grafana
depends_on:
- prometheus
volumes:
grafana_data:
注意:默认管理员密码为 secret,部署前务必改为自定义密码。
五、如何自定义 Tracing(源码级扩展)
TaskWeaver 的埋点基于 OpenTelemetry Python SDK 实现。若需深度定制追踪行为,需要修改 TaskWeaver 代码。为了把 OpenTelemetry SDK 的细节从业务代码中隔离,TaskWeaver 在 taskweaver/module/tracing.py 中封装了一层抽象。
1. Tracing 类:核心封装
Tracing 类是对 OpenTelemetry SDK 的包装,对外提供以下静态方法:
| 方法 | 作用 |
|---|---|
set_span_status(status_code, status_message) |
设置当前 span 的状态(OK 或 ERROR);为 OK 时会清空状态消息 |
set_span_attribute(key, value) |
为当前 span 设置属性(attribute),如用户查询、生成的代码等 |
set_span_exception(exception) |
在 span 上记录异常 |
add_prompt_size(size, labels) |
向 prompt_size 计数器累加数值,可携带 direction 等标签 |
count_tokens(data) |
使用 tiktoken 编码器计算字符串的 Token 数(未启用时返回 0) |
在初始化时,Tracing 会根据配置完成一系列底层装配(见 taskweaver/module/tracing.py):
- 根据
exporter配置创建导出器:otlp使用OTLPSpanExporter/OTLPMetricExporter(指向tracing.endpoint),console使用ConsoleSpanExporter/ConsoleMetricExporter; - 通过
BatchSpanProcessor将 span 异步批量导出,并设置全局 TracerProvider 与 MeterProvider; - 创建
prompt_size计数器与tiktoken.encoding_for_model(...)编码器。
2. 两个追踪装饰器
框架提供了两个装饰器用于追踪函数调用(见 taskweaver/module/tracing.py):
tracing_decorator:用于类方法,生成的 span 名为ClassName.method_name(自动从第一个参数推断类名);tracing_decorator_non_class:用于普通函数,span 名即函数名。
二者的内部实现都会判断全局 tracer 是否存在——未启用 Tracing 时直接执行原函数,零开销。
3. 手动创建 span 上下文
当需要手动创建一个追踪上下文时,使用:
with get_tracer().start_as_current_span("span_name") as span:
# your code
get_tracer() 在 Tracing 未启用时会返回 DummyTracer——一个所有方法均为空操作的占位实现(见 taskweaver/module/tracing.py),从而保证业务代码无需关心是否启用。
装饰器用法示例:
@tracing_decorator
def your_function(self, *args, **kwargs):
# your code
4. 埋点在核心模块中的实际落点
从源码结构看,埋点已覆盖任务执行的主要链路:
- Planner(taskweaver/planner/planner.py):回复函数
reply使用@tracing_decorator埋点;记录user_query、use_experience、发送给 LLM 的完整prompt(json.dumps(chat_history))、通过count_tokens计算的prompt_size,并调用add_prompt_size上报指标;回复阶段记录out.from、out.to、out.message、out.attachments等 post 属性; - CodeInterpreter(taskweaver/code_interpreter/code_interpreter/code_interpreter.py):生成/解释流程使用
@tracing_decorator;记录生成的code、code_verification_on开关,代码校验阶段通过get_tracer().start_as_current_span("CodeInterpreter.verify_code")建立子 span,并在失败时记录verification_error; - CodeExecutor(taskweaver/code_interpreter/code_executor.py):执行流程使用
@tracing_decorator,内部以start、load_plugin、run_code等子 span 细分执行阶段,并记录执行的code属性。
5. 测试用例验证
单元测试 tests/unit_tests/test_tracing.py 覆盖了 Tracing 的两种运行状态:
test_tracing_disabled:配置tracing.enabled=false,验证set_span_attribute、set_span_status、set_span_exception、start_as_current_span、两个装饰器等 API 在禁用状态下均可安全调用(内部走 DummyTracer 空实现,不抛异常);test_tracing_enabled:配置tracing.enabled=true、tracing.exporter=console(控制台导出,无需外部 Collector 即可本地验证),执行相同的 API 调用后sleep(5)等待BatchSpanProcessor异步导出。
这两个用例可以作为自定义埋点时的行为参照:禁用时无副作用,启用时数据经导出器异步上报。
小结
通过本文,你已掌握 TaskWeaver Telemetry 的完整使用链路:安装依赖并配置 项目配置文件 中的 tracing.* 参数;用 tracing/docker-compose.yaml 一键拉起 OpenTelemetry Collector、Jaeger 与 Prometheus;在 Jaeger 中分析任务时间线、关键路径与 span 详情,在 Prometheus 中通过 prompt_size_total 观察 Token 消耗趋势;并了解如何基于 taskweaver/module/tracing.py 的 Tracing 类、tracing_decorator 与 get_tracer() 扩展自定义埋点。这套可观测能力将显著提升对多角色协作型数据分析 Agent 的调试与性能优化效率。



