LangGraph 分布式追踪：为什么你的 Agent 执行链总是“黑盒”？

这篇文章帮你搞定 LangGraph 分布式追踪的底层原理从 Trace/Span 到全链路可观测阅读提示适合谁看有 LangGraph 或 LLM 应用开发经验正在做生产级可观测性的工程师看完能做什么能设计可追踪、可调试、可监控的分布式追踪系统不适合谁还没理解 LangGraph State/Graph 基础概念的纯新手先给结论追踪不是“打印日志”而是结构化的 Trace/Span 数据每个节点执行都是一个 SpanSpan 之间通过 TraceID 关联生产级追踪必须考虑采样策略、上下文传播、 exporter 选型很多人做 LangGraph 时demo 阶段跑得很顺一上生产就发现 Agent 执行链是“黑盒”不知道哪个节点耗时最长出错时不知道哪个节点出问题性能瓶颈无法定位看起来是日志问题本质上是分布式追踪没设计好。01 分布式追踪的本质Trace 与 Span分布式追踪的核心思想是Trace 与 SpanTrace一次完整的执行链包含所有 SpanSpan执行链中的一个步骤包含开始时间、结束时间、状态TraceIDTrace 的唯一标识所有 Span 共享SpanIDSpan 的唯一标识用于关联父子关系这意味着每个节点执行都是一个 SpanSpan 之间通过 TraceID 关联父子 Span 通过 ParentSpanID 关联为什么不能用日志代替# 误区用日志记录执行链def execute_node(state): print(fNode started: {node_name}) result process(state) print(fNode finished: {node_name}) return result这种写法的问题在于日志是文本无法结构化查询无法关联父子关系无法计算耗时无法做采样和聚合LangGraph 的解法是把追踪变成Trace Span ExporterTrace一次完整的执行链Span执行链中的一个步骤Exporter把 Span 数据导出到 Jaeger/Zipkin场景代码示例分布式追踪配置from opentelemetry import tracefrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessorfrom opentelemetry.exporter.jaeger.thrift import JaegerExporter# 1) 初始化 Tracerprovider TracerProvider()jaeger_exporter JaegerExporter( agent_host_namelocalhost, agent_port6831,)provider.add_span_processor(BatchSpanProcessor(jaeger_exporter))trace.set_tracer_provider(provider)tracer trace.get_tracer(langgraph-agent)# 2) 运行入口验证配置是否成功if __name__ __main__: print(Tracer configured:, tracer)02 Span 的底层原理执行步骤的结构化记录图 2Span 执行流程Span 的核心是执行步骤的结构化记录开始时间Span 开始的时间戳结束时间Span 结束的时间戳状态Span 的执行状态OK/ERROR属性Span 的附加信息key-value这意味着Span 不是“日志行”而是“结构化数据”Span 可以嵌套形成父子关系Span 可以导出到外部系统做可视化和分析场景代码示例Span 的使用方式from opentelemetry import tracetracer trace.get_tracer(langgraph-agent)def execute_node(state): # 创建 Span with tracer.start_as_current_span(execute_node) as span: # 设置属性 span.set_attribute(node_name, my_node) span.set_attribute(input, str(state)) # 执行逻辑 result process(state) # 设置状态 span.set_status(trace.StatusCode.OK) span.set_attribute(output, str(result)) return result# 最小验证if __name__ __main__: print(execute_node ready)03 上下文传播跨节点的 Trace 关联图 3上下文传播机制上下文传播是分布式追踪的关键TraceContext携带 TraceID 和 SpanID传播方式通过 HTTP Header 或 gRPC Metadata自动传播OpenTelemetry 自动注入和提取这意味着跨节点调用时TraceContext 自动传播子节点自动继承父节点的 TraceID无需手动传递 TraceID场景代码示例上下文传播配置from opentelemetry import tracefrom opentelemetry.propagate import set_global_textmapfrom opentelemetry.propagators.composite import CompositePropagatorfrom opentelemetry.propagators.tracecontext import TraceContextTextMapPropagator# 1) 配置传播器set_global_textmap( CompositePropagator([TraceContextTextMapPropagator()]))# 2) 运行入口验证传播器配置if __name__ __main__: print(Propagator configured)04 最小实验观察追踪如何工作实验条件环境LangGraph latestPython 3.10Jaeger输入一个简单任务包含两个节点预期观察Jaeger 中看到两个 Span通过 TraceID 关联先准备什么启动 Jaeger配置 OpenTelemetry先跑什么执行任务观察 Jaeger 中的 Span你应该看到什么两个 Span通过 TraceID 关联代码 1from opentelemetry import tracefrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessorfrom opentelemetry.exporter.jaeger.thrift import JaegerExporter# 配置 Tracerprovider TracerProvider()jaeger_exporter JaegerExporter( agent_host_namelocalhost, agent_port6831,)provider.add_span_processor(BatchSpanProcessor(jaeger_exporter))trace.set_tracer_provider(provider)tracer trace.get_tracer(langgraph-agent)def node_a(state): with tracer.start_as_current_span(node_a) as span: span.set_attribute(input, str(state)) return {result: a}def node_b(state): with tracer.start_as_current_span(node_b) as span: span.set_attribute(input, str(state)) return {result: b}# 测试# with tracer.start_as_current_span(root) as root_span:# result_a node_a({task: test})# result_b node_b(result_a)# root_span.set_attribute(output, str(result_b))如果结果不符合预期先看哪里Jaeger 是否正常连接TraceID 是否正确传播Span 是否正确创建Exporter 是否正确导出05 跑出来不对时先看这几件事现象 1Jaeger 中看不到 Span → 可能 Exporter 配置错误先检查连接现象 2Span 之间没有关联 → 可能上下文传播未生效先检查 Propagator现象 3Span 耗时不准确 → 可能时间戳错误先检查时区现象 4采样率太低 → 可能采样策略配置错误先检查 Sampler06 什么时候该用什么时候别急着上更适合复杂 Agent 执行链、生产级可观测性、性能分析不适合简单任务、原型验证、低并发场景成本会突然变高的点Span 存储、采样策略、Exporter 选型3 问判断法你的 Agent 是否包含多个节点是否需要定位性能瓶颈是否需要生产级可观测性如果 3 个问题大多是否定先不要上复杂方案。07 小结从“日志”到“结构化追踪”分布式追踪的底层原理可以总结成三句话Trace 是核心一次完整的执行链包含所有 SpanSpan 是关键执行步骤的结构化记录支持嵌套和关联上下文是保障TraceContext 自动传播跨节点关联当你把追踪从“日志”升级为“结构化追踪”系统才真正具备可调试性、可监控性和可优化性。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】