跳转至

Trace服务

FastDeploy 基于OpenTelemetry Collector 导出请求追踪数据。 可通过在启动服务器时添加 --trace-enable 来开启追踪，并使用 --otlp-traces-endpoint 配置 OpenTelemetry Collector 接收端点。

配置指南（Setup Guide）

1. 安装依赖和工具

# 手动安装
pip install opentelemetry-sdk opentelemetry-api opentelemetry-exporter-otlp opentelemetry-exporter-otlp-proto-grpc

2. 启动 OpenTelemetry Collector 和 Jaeger

docker compose -f examples/observability/tracing/tracing_compose.yaml up -d

3. 启动带追踪功能的 FastDeploy 服务器

  • FastDeploy设置环境变量
# 开启Trace
"TRACES_ENABLE": "true",
# 服务名称
"FD_SERVICE_NAME": "FastDeploy",
# 实例名称
"FD_HOST_NAME": "trace_test",
"TRACES_EXPORTER": "otlp",
# grpc方式导出端口为4317， http方式导出端口为4318
"EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"EXPORTER_OTLP_HEADERS": "Authentication=Txxxxx",
# 导出方式
"OTEL_EXPORTER_OTLP_TRACES_PROTOCOL": "grpc",
  • 启动FastDeploy

4. 发送请求并观察追踪数据

  • 在浏览器访问 Jaeger UI（端口 16686）可视化请求追踪。

  • Collector 同时会将追踪数据导出为 /tmp/otel_trace.json。

如何为自己的代码添加追踪

FastDeploy 已在主要节点插入了追踪点。开发者可使用 trace.py 提供的 API 进行更精细的追踪。

4.1 初始化追踪

每个涉及追踪的进程执行：

process_tracing_init()

请求涉及到的每个线程执行：

trace_set_thread_info("thread_label", tp_rank, dp_rank)
  • thread_label 用于线程区分，可视化显示
  • tp_rank/dp_rank 可选，标记张量并行或数据并行 rank

4.2 标记请求开始和结束

trace_req_start(rid, bootstrap_room, ts, role)
trace_req_finish(rid, ts, attrs)
  • 会创建 Bootstrap Room Span与 Root Span
  • 支持 FastAPI Instrumentor 已创建 Span 的继承（context copy）
  • attrs 可添加额外属性

4.3 为 Slice 添加追踪

普通 Slice：

trace_slice_start("slice_name", rid)
trace_slice_end("slice_name", rid)
  • 最后一个 Slice 可标记线程结束：
trace_slice_end("slice_name", rid, thread_finish_flag=True)

4.4 请求跨线程 Trace Context 传播

发送端（ZMQ）：

trace_context = trace_get_proc_propagate_context(rid)
req.trace_context = trace_context

接收端（ZMQ）：

trace_set_proc_propagate_context(rid, req.trace_context)

4.5 添加事件和属性

事件（记录到当前 Slice）：

trace_event("event_name", rid, ts, attrs)

属性（添加到当前 Slice）：

trace_slice_add_attr(rid, attrs)

扩展追踪框架

5.1 Trace Context 层级

  • 两级 Trace Context：
  • TraceReqContext → 请求级上下文
  • TraceThreadContext → 线程级上下文
  • 三级 Span 结构：
  • req_root_span
  • thread_span
  • slice_span

5.2 可用的 Span 名枚举（TraceSpanName）

FASTDEPLOY
PREPROCESS
SCHEDULE
PREFILL
DECODE
POSTPROCESS
  • 在创建 slice 时可使用枚举，保证命名规范化

5.3 注意事项

  1. 每个线程 Span 必须在最后一个 Slice 结束时关闭。
  2. FastAPI Instrumentor 已创建的 Span 会被继承到内部追踪上下文。