TaskWeaver 遥测(Telemetry)实战指南:基于 OpenTelemetry 的追踪、指标与性能瓶颈分析

原创2026-10-09 12:06:051,706 阅读
文章标签:AI Agent数据分析

TaskWeaver 遥测(Telemetry)实战指南:基于 OpenTelemetry 的追踪、指标与性能瓶颈分析

TaskWeaver 作为面向数据分析任务的 code-first Agent 框架,其执行链路横跨 Planner、CodeGenerator、CodeExecutor 等多个角色与模块。本文围绕官方文档 telemetry.md 展开,完整讲解如何借助 OpenTelemetry 为 TaskWeaver 启用分布式追踪(Tracing)与指标(Metrics)采集,覆盖启用配置、基础设施搭建、Jaeger/Prometheus 可视化查询,以及基于 taskweaver/module/tracing.py 的源码级自定义扩展。读完本文,你将能够在自己的 TaskWeaver 项目中复现一套可观测体系,精确定位一次数据分析任务的耗时瓶颈、Token 消耗与错误来源。

TaskWeaver 追踪视图

上图展示了一个典型任务(分析一个上传的文件)的追踪时间线。可以看到任务执行被划分为三个主要阶段:

  • 规划阶段(Planning):Planner 决定需要执行的子任务;
  • 代码生成与执行阶段(Code generation & execution):CodeGenerator 生成代码,CodeExecutor 执行代码;
  • 回复阶段(Reply):Planner 将回复发送给用户。

时间线中带有黑色描边的条代表任务执行的关键路径(critical path),即贯穿整个任务的最长路径,它是定位执行瓶颈的最直接依据。从默认场景的追踪结果可以清楚看到:当前任务的执行时间主要被对 LLM 的调用所主导。

一、TaskWeaver 能追踪哪些内容

启用 Telemetry 后,OpenTelemetry 的埋点会覆盖以下五类信息:

  1. 角色间交互:Planner、CodeInterpreter 与 Executor 之间的消息流转;
  2. 各角色与核心组件的耗时:每个角色及主要模块消耗的时间;
  3. LLM 的 Prompt 与响应:发送给 LLM 的 Prompt 原文与收到的响应;
  4. 任务状态与错误:任务的执行状态(OK/ERROR)以及遇到的异常;
  5. Token 消耗:每个角色消耗的 Token 数量。

点击任意一个 span(追踪中的最小工作单元),可以查看该 span 的详细属性与日志。以下截图展示了 Planner 回复函数的 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(指标后端)。

TaskWeaver 追踪架构

基础设施所需的编排文件位于仓库的 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 中的 prompt_size 指标

在 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 的调试与性能优化效率。

登录后查看全文
TaskWeaver