Yanshi 工作流追踪系统使用指南
版本: v1.0 日期: 2025-11-23 状态: ✅ Production Ready
🎯 概述
Yanshi 追踪系统提供详细的工作流执行追踪,包括:
- ✅ 每个节点的输入/输出
- ✅ LLM 提示词和响应
- ✅ Token 使用和成本
- ✅ 执行时间和性能指标
- ✅ 完整的调试日志
核心特性
- 不污染核心 - 通过 EventListener 集成,零侵入
- 零开销 - 不启用时无性能影响
- 灵活存储 - 文件存储(开发)、数据库(生产)
- 异步处理 - 不阻塞工作流执行
- 可查询 - 支持过滤、分页、时间范围
关联上下文
持久化 trace 在每个层级都包含显式 context 字段,用来把一次
mixed run 串成同一棵树:
- workflow:
context.run_id/context.trace_id等于 workflow run id,span_id = "workflow" - node:
span_id = "node:<node_id>",父 span 是workflow - agent:
span_id = "agent:<session_id>",父 span 是所在 workflow node - tool/MCP call:
span_id = "tool:<index>:<tool>",父 span 是 agent
这些字段会直接写入 JSON trace,并与 OpenTelemetry exporter 的 span 层级保持一致。
Tool call trace 同时记录 source、permissions、duration_ms 和
is_error。这些字段来自 ToolRegistry 中注册工具的 metadata,以及
runtime 对实际调用结果的计时和错误状态。
📦 快速开始
1. 添加依赖
[dependencies]
yanshi-core = "0.3.0"
yanshi-tracing = "0.1.0"
2. 基本使用
use yanshi_core::events::{EventListener, WorkflowEvent};
use yanshi_tracing::{
TraceCollector,
TraceConfig,
storage::file::FileTraceStorage,
TraceStorage,
format_trace_human_readable,
};
use std::sync::Arc;
use std::path::PathBuf;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// 1. 创建存储
let storage = Arc::new(FileTraceStorage::new(
PathBuf::from("./traces")
)?);
// 2. 创建追踪收集器
let collector = Arc::new(TraceCollector::new(
storage.clone(),
TraceConfig::development() // 或 TraceConfig::production()
));
// 3. 使用收集器(实现 EventListener trait)
// collector.on_event(&event);
// 4. 查询追踪
let trace = storage.get_trace("workflow-id").await?;
if let Some(t) = trace {
println!("{}", format_trace_human_readable(&t));
}
Ok(())
}
⚙️ 配置选项
TraceConfig
#![allow(unused)]
fn main() {
use yanshi_tracing::{TraceConfig, StorageErrorPolicy};
// 开发环境配置(完整追踪)
let dev_config = TraceConfig::development();
// 生产环境配置(脱敏)
let prod_config = TraceConfig::production();
// 自定义配置
let custom_config = TraceConfig {
capture_io: true, // 是否捕获输入/输出
capture_prompts: true, // 是否捕获 LLM 提示词
max_io_size_bytes: 1024 * 1024, // 最大数据大小(1MB)
async_storage: true, // 异步存储(推荐)
on_storage_error: StorageErrorPolicy::LogError,
};
}
配置对比
| 配置项 | 开发环境 | 生产环境 | 说明 |
|---|---|---|---|
capture_io | ✅ true | ❌ false | 生产环境可能包含敏感数据 |
capture_prompts | ✅ true | ❌ false | LLM 提示词可能包含敏感信息 |
max_io_size_bytes | 10MB | 0 | 限制日志大小 |
async_storage | ✅ true | ✅ true | 异步存储不阻塞工作流 |
💾 存储后端
1. 文件存储(开发环境)
#![allow(unused)]
fn main() {
use yanshi_tracing::storage::file::FileTraceStorage;
use std::path::PathBuf;
let storage = FileTraceStorage::new(
PathBuf::from("./traces")
)?;
// 每个工作流一个 JSON 文件
// ./traces/workflow-001.json
// ./traces/workflow-002.json
}
优点:
- 简单易用
- 无需数据库
- 适合本地开发
缺点:
- 查询性能差
- 不适合大规模生产
2. PostgreSQL / SQLite 存储(尚未实现)
W4.4:storage::schema 模块导出了两套 DDL 常量
(POSTGRES_TRACE_SCHEMA/SQLITE_TRACE_SCHEMA,5 表规范化 schema),但
没有任何代码执行这些 DDL 或实现 TraceStorage trait——yanshi-tracing
crate 里唯一的具体存储后端是上面的 FileTraceStorage。此前存在的
postgres Cargo feature 只挂了一个零引用的 sqlx 可选依赖(一个死
flag),已在 W4.4 移除;cargo check --features postgres 编译通过从来
不能证明有真实的 Postgres 后端。
如果未来需要 SQL 后端,需要把 ExecutionTrace 拆分写入
trace_runs/trace_steps/trace_events/trace_tool_calls/
trace_mcp_calls 五张表(不是简单塞进一个 JSONB 列),这是一项独立的、
需要单独 RFC 的工作量,不是“填一个存根“级别的任务。
📡 OTLP 导出(W4.4)
otlp-http feature(默认不启用)提供开箱即用的 OTLP/HTTP+JSON span
导出器 OtlpHttpSpanSink,基于官方 opentelemetry-otlp crate 构建,
wire 编码由该 crate 保证符合规范,不需要手写 OTLP 的 JSON schema。
[dependencies]
yanshi-tracing = { version = "0.1", features = ["otlp-http"] }
#![allow(unused)]
fn main() {
use std::sync::Arc;
use yanshi_tracing::{
OtelExporterConfig, OtelTraceExporter, TraceCollector, TraceConfig,
};
use yanshi_tracing::otlp::{OtlpHttpConfig, OtlpHttpSpanSink};
use yanshi_tracing::storage::file::FileTraceStorage;
use std::path::PathBuf;
let storage = Arc::new(FileTraceStorage::new(PathBuf::from("./traces"))?);
// OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_HEADERS 环境变量
// (标准 OTel SDK 约定),或手动构造:
let otlp_config = OtlpHttpConfig::from_env()
.unwrap_or_else(|| OtlpHttpConfig::new("http://localhost:4318"));
let sink = OtlpHttpSpanSink::new(otlp_config)?;
let exporter = OtelTraceExporter::new(
OtelExporterConfig::new("my-service"),
sink,
);
let collector = TraceCollector::new(storage, TraceConfig::production())
.with_exporter(Arc::new(exporter));
}
只支持 HTTP 传输(“HTTP 先行”,见 TODOs.md W4.4);gRPC 传输仍未实现,
需要的话仍需自行实现 OtelSpanSink。批处理粒度是“每个完成的
ExecutionTrace 一次导出“(跟随 TraceCollector 自身的批处理边界),
不经过 OTel SDK 自己的 batch processor / sampler / 全局 tracer 注册。
🔍 查询追踪
获取单个追踪
#![allow(unused)]
fn main() {
use yanshi_tracing::TraceStorage;
// 通过 workflow_id 查询
let trace = storage.get_trace("workflow-001").await?;
if let Some(trace) = trace {
println!("Status: {:?}", trace.status);
println!("Duration: {}ms", trace.duration_ms().unwrap_or(0));
println!("Nodes: {}", trace.nodes.len());
}
}
查询多个追踪
#![allow(unused)]
fn main() {
use yanshi_tracing::{TraceQuery, TraceStatus};
use chrono::{Utc, Duration};
// 构建查询
let query = TraceQuery {
status: Some(TraceStatus::Completed),
user_id: Some("user-123".to_string()),
time_range: Some(TimeRange {
start: Utc::now() - Duration::days(7),
end: Utc::now(),
}),
limit: Some(50),
offset: Some(0),
..Default::default()
};
// 执行查询
let traces = storage.query_traces(query).await?;
for trace in traces {
println!("Workflow: {}", trace.workflow_id);
}
}
📊 格式化输出
人类可读格式
#![allow(unused)]
fn main() {
use yanshi_tracing::format_trace_human_readable;
let trace = storage.get_trace("workflow-001").await?.unwrap();
let output = format_trace_human_readable(&trace);
println!("{}", output);
}
输出示例:
═══════════════════════════════════════════════════════════
Workflow: AI Research Assistant
ID: workflow-001
═══════════════════════════════════════════════════════════
Status: Completed
Started: 2025-11-23 10:30:00 UTC
Completed: 2025-11-23 10:30:45 UTC
Duration: 45000ms
Environment: production
User: user-123
Tags: research, arxiv
───────────────────────────────────────────────────────────
Nodes Executed: 3
───────────────────────────────────────────────────────────
[1] search_arxiv (HttpNode)
Status: Completed
Duration: 5000ms
Input: {"query": "large language models"}
Output: {"papers": [...]}
[2] summarize (LLMNode)
Status: Completed
Duration: 30000ms
Model: gpt-4o (openai)
System Prompt: You are a research assistant...
User Prompt: Summarize the following papers...
Response: Here is a summary of the papers...
Tokens: 1500 (prompt) + 500 (completion) = 2000
Cost: $0.06
Latency: 30000ms
[3] generate_report (TemplateNode)
Status: Completed
Duration: 100ms
═══════════════════════════════════════════════════════════
JSON 格式
#![allow(unused)]
fn main() {
use yanshi_tracing::export_trace_json;
let json = export_trace_json(&trace)?;
println!("{}", json);
// 或保存到文件
std::fs::write("trace-001.json", json)?;
}
简洁摘要
#![allow(unused)]
fn main() {
use yanshi_tracing::format_trace_summary;
let summary = format_trace_summary(&trace);
println!("{}", summary);
// 输出: ✅ workflow-001 | completed | 3 nodes | 45000ms
}
终端调试视图
yanshi trace tui 提供最小的静态 TUI timeline,用于在不重新执行 workflow、tool、MCP server 或 LLM 的情况下聚焦查看已持久化 trace。
yanshi trace tui workflow-001 --dir ./traces
yanshi trace tui workflow-001 --dir ./traces --filter mcp --details
yanshi trace tui workflow-001 --dir ./traces --filter agent --max-field-chars 240
If --dir is omitted, trace commands read YANSHI_TRACE_DIR first and then
fall back to ~/.yanshi/traces:
YANSHI_TRACE_DIR=./traces yanshi trace replay workflow-001
YANSHI_TRACE_DIR=./traces yanshi trace tui workflow-001 --filter agent
可用 filter:
all: workflow、node、agent、tool/MCP 调用。workflow: workflow 和 node 层级概览。agent: agent session、step 数量、tool 数量。tool: 所有 tool 调用。mcp: 只显示 MCP tool 调用。
📝 事件类型
工作流事件
#![allow(unused)]
fn main() {
use yanshi_core::events::WorkflowEvent;
// 工作流开始
WorkflowEvent::WorkflowStarted {
workflow_id: String,
timestamp: Instant,
}
// 工作流完成
WorkflowEvent::WorkflowCompleted {
workflow_id: String,
duration: Duration,
timestamp: Instant,
}
// 工作流失败
WorkflowEvent::WorkflowFailed {
workflow_id: String,
error: String,
duration: Duration,
timestamp: Instant,
}
}
节点事件
#![allow(unused)]
fn main() {
// 节点开始
WorkflowEvent::NodeStarted {
workflow_id: String,
node_id: String,
timestamp: Instant,
}
// 节点完成
WorkflowEvent::NodeCompleted {
workflow_id: String,
node_id: String,
duration: Duration,
timestamp: Instant,
}
// 节点失败
WorkflowEvent::NodeFailed {
workflow_id: String,
node_id: String,
error: String,
duration: Duration,
timestamp: Instant,
}
}
LLM 专用事件
#![allow(unused)]
fn main() {
// LLM 提示词发送
WorkflowEvent::LLMPromptSent {
workflow_id: String,
node_id: String,
model: String, // "gpt-4o"
provider: String, // "openai"
system_prompt: Option<String>,
user_prompt: String,
temperature: Option<f32>,
max_tokens: Option<u32>,
timestamp: Instant,
}
// LLM 响应接收
WorkflowEvent::LLMResponseReceived {
workflow_id: String,
node_id: String,
model: String,
response: String,
usage: Option<TokenUsage>, // Token 统计
duration: Duration,
timestamp: Instant,
}
}
🔧 高级用法
自定义 EventListener
#![allow(unused)]
fn main() {
use yanshi_core::events::{EventListener, WorkflowEvent};
struct MyCustomListener {
// 你的字段
}
impl EventListener for MyCustomListener {
fn on_event(&self, event: &WorkflowEvent) {
match event {
WorkflowEvent::LLMPromptSent { model, user_prompt, .. } => {
// 发送到 Sentry
// sentry::capture_message(&format!("LLM call to {}", model));
}
WorkflowEvent::WorkflowFailed { error, .. } => {
// 发送告警
// alert::send_notification(error);
}
_ => {}
}
}
}
}
组合多个监听器
#![allow(unused)]
fn main() {
use yanshi_core::events::MultiListener;
let multi_listener = MultiListener::new(vec![
Box::new(TraceCollector::new(storage, config)),
Box::new(MyMetricsListener),
Box::new(MyAlertsListener),
]);
// 所有监听器都会收到事件
}
📈 性能考虑
1. 异步存储
#![allow(unused)]
fn main() {
let config = TraceConfig {
async_storage: true, // 推荐!
..Default::default()
};
}
影响:
- ✅ 不阻塞工作流执行
- ✅ 存储失败不影响工作流
- ⚠️ 需要等待异步任务完成才能查询
2. 数据大小限制
#![allow(unused)]
fn main() {
let config = TraceConfig {
max_io_size_bytes: 1024 * 1024, // 1MB
..Default::default()
};
}
防止:
- 日志文件过大
- 内存占用过高
- 查询性能下降
3. 数据脱敏(生产环境)
#![allow(unused)]
fn main() {
let config = TraceConfig::production(); // 自动脱敏
// 或手动配置
let config = TraceConfig {
capture_io: false, // 不捕获输入/输出
capture_prompts: false, // 不捕获提示词
..Default::default()
};
}
🐛 调试和故障排查
检查追踪是否保存
#![allow(unused)]
fn main() {
// 等待异步存储完成
tokio::time::sleep(Duration::from_millis(200)).await;
// 检查追踪
let trace = storage.get_trace("workflow-id").await?;
if trace.is_none() {
println!("❌ Trace not found! Check storage configuration.");
}
}
查看错误策略
#![allow(unused)]
fn main() {
let config = TraceConfig {
on_storage_error: StorageErrorPolicy::LogError, // 记录错误
// or
on_storage_error: StorageErrorPolicy::Ignore, // 忽略错误
..Default::default()
};
}
没有“存储失败就让工作流失败“的选项:trace 由后台 drain 任务在工作流产出结果之后才落盘, 此时工作流已经结束。
查看正在运行的工作流
#![allow(unused)]
fn main() {
let running = collector.list_running().await;
println!("Running workflows: {}", running.len());
for trace in running {
println!(" - {}: {} nodes", trace.workflow_id, trace.nodes.len());
}
}
📚 示例
完整示例
参见 yanshi-tracing/examples/simple_tracing.rs
运行:
cargo run --example simple_tracing -p yanshi-tracing
输出示例
╔══════════════════════════════════════════════════════╗
║ Yanshi Tracing System - Simple Example ║
╚══════════════════════════════════════════════════════╝
🚀 Simulating workflow execution: demo-workflow-001
✓ Workflow started
✓ Node 'fetch_papers' started
✓ Node 'fetch_papers' completed (200ms)
✓ Node 'summarize' started
✓ LLM prompt sent to gpt-4o
✓ LLM response received (300ms, 2000 tokens)
✓ Node 'summarize' completed (400ms)
✓ Workflow completed (750ms total)
📊 Retrieving execution trace...
[完整追踪输出...]
📈 Statistics:
- Total nodes executed: 2
- Duration: 813ms
- Total tokens used: 2000
- LLM latency: 300ms
✅ Example completed successfully!
🌐 W3C Trace Context 端到端连续
自 v0.3.0 起,Yanshi 在每个 LLM HTTP 出站调用上注入 W3C
traceparentheader,让 OTel-aware 服务器(Jaeger / Tempo / Honeycomb / 自建网关)能把 LLM 一跳作为 Yanshi 的子 span 接进同一棵 trace,避免在 LLM 边界断开。
工作原理
yanshi_llm::LlmTraceContext { trace_id, span_id, flags }是 W3C wire 格式的 typed 包装。trace_id32 hex /span_id16 hex。- 模块用 tokio task-local
保存当前 context;用
yanshi_llm::trace_context::scope(ctx, fut).await设置一次,包裹的 future 内所有 LLM 调用都会自动看到。 - 每个 provider(OpenAI / Anthropic / Google / Moonshot / StepFun)的
build_headers()末尾调用inject_into_headers(&mut headers),读取 task-local 并写出traceparent: 00-{trace_id}-{span_id}-{flags}。
自动传播
AgentContext::trace_context: Option<LlmTraceContext> 默认为 None;当
非空时,ReActAgent / PlanExecuteAgent 在每次 LLMClient 调用前
通过 .trace_context(ctx.trace_context.clone()) builder 透传。这样
agent → LLM HTTP 这一跳的 trace 永远连贯。
显式调用(不走 agent runtime)
#![allow(unused)]
fn main() {
use yanshi_llm::{Yanshi, LlmTraceContext};
let ctx = LlmTraceContext::random();
let answer = Yanshi::model("gpt-4o-mini")
.prompt("hello")
.trace_context(ctx) // ← 出站 HTTP 现在带 traceparent
.execute()
.await?;
}
与 OTel 后端对接
把 LlmTraceContext::trace_id / span_id 对齐到现有 OTel SDK:
- 已经在用
opentelemetry-rust:从 active span 取SpanContext,LlmTraceContext::new(span_ctx.trace_id().to_string(), span_ctx.span_id().to_string())。 - 只用
yanshi-tracing内置 exporter:yanshi-tracing/src/otel.rs里的trace_id/span_id生成 W3C 规范要求的随机 16/8 字节 ID(Q2.2.2 修正——此前是从workflow_id派生的确定性 ID,违反 W3C “MUST be random” 要求,已废弃)。跨进程一致性通过ExecutionTrace.metadata. external_trace_id/external_parent_span_id承接入站traceparent实现(trace_to_spans优先用这两个字段,没有才回退到随机生成),而不 是靠确定性派生。W4.4:yanshi-tracing::otlp(otlp-httpfeature) 现在提供开箱即用的 OTLP/HTTP 导出器,不必再自己实现OtelSpanSink。
何时不会注入
AgentContext::trace_context = None(默认):不注入。- 直接调用 provider 而未走
LLMClient::with_trace_context、也未在 task-local 中安装 context:不注入。
不注入 = 行为与 v0.2.0 完全一致,向后兼容。
🚀 下一步
- 查看示例:
cargo run --example simple_tracing - 阅读设计文档:
docs/TRACING_DESIGN.md - 集成到你的工作流: 添加 TraceCollector as EventListener
- 配置存储: 选择合适的存储后端
📖 相关文档
维护者: Yanshi Team 问题反馈: GitHub Issues 最后更新: 2025-11-23