凌晨两点多被告警电话叫起来核心服务P99从80ms直接飙到快2秒看监控大屏一切正常CPU不高、内存稳定、错误率也没有明显波动但用户的请求就是肉眼可见地变慢。如果你也经历过这种靠猜来排查线上问题的阶段就会明白为什么微服务架构铺开之后分布式追踪不是锦上添花而是刚需。这次借FastAPI这个框架把分布式追踪里最核心也最容易让人绕晕的两个概念——Span和Scope一次性掰开揉碎讲清楚顺便附上可以直接抄走的落地方案。这篇文章适合两类人一类是FastAPI后端开发者想给服务接上可观测性能力但不知道从哪下手另一类是已经在用OpenTelemetry、但老是被“为什么我的Span没有父子关系”“为什么上下文会串线”这类问题卡住的人。读完你会明白Span记录的是什么、Scope管理的是什么以及这两者在FastAPI的异步模型下到底怎么协作。1. 为什么FastAPI服务需要分布式追踪从一条慢请求说起1.1 日志和指标为什么不够用先聊一个很实际的问题服务变慢了日志里有堆栈吗指标里有调用链吗单体应用时代问题其实好定位。一个请求进来Controller → Service → DAO → Database调用层级是固定的线程栈一抓就能看出时间耗在哪。日志虽然分散但好歹是线性的一条线对着时间戳找基本能拼出原貌。但到了微服务阶段就完全不一样了。一个下单请求可能先经过网关再调用户服务、库存服务、支付服务支付服务里面还要调第三方支付网关的回调回调里面又带着异步任务去更新订单状态。日志分散在少则五六个、多则十几二十个服务实例里每个服务记录的只是自己那一段“局部视角”靠人肉拼日志还原一次完整的请求路径成本极高准确率也低。监控指标解决的是另外一个维度的问题它回答的是“系统整体状态怎么样”比如QPS多少、平均延迟多少、错误率多少。但它回答不了“这一次请求具体经历了什么”。指标是照片分布式追踪是录像这就是两者最本质的区别。要排查一条慢请求到底慢在哪个环节、哪一次外部调用拖了后腿就必须有追踪数据。1.2 FastAPI的异步并发让问题更难定位FastAPI在国内外的使用量近几年涨得很猛很多人看中它的异步性能和类型提示带来的开发体验。但异步框架有一个“天然盲区”并发粒度极细单线程事件循环可以在毫秒级别切换大量协程一个请求可能因为await一个IO操作就把执行权让给另外几百个请求。传统同步Web框架里一次请求基本对应一个线程出问题的时候线程栈能直接把调用关系拍在你脸上。FastAPI这种基于asyncio的模式下你很难从线程栈里看出“这个协程是哪个请求的”因为同一时间一个线程里可能交替执行着上千个协程——它们共享同一个线程ID却分属完全不同的业务请求。这时候就需要一种“请求级别的上下文”来跟踪从请求进来开始把它在服务内部的每一次函数调用、每一次数据库访问、每一次外部HTTP请求串成一条逻辑链路。这条链路上每个节点就是一个Span而怎么让新建出来的Span自动知道“我是这条链路的一部分、我的父亲是谁”就是Scope要解决的活。2. Span分布式追踪里的最小工作单元2.1 Span的核心结构与生命周期Span在概念上非常好理解它就是一次操作的时间片段。打个比方你要记录“处理一个订单”这件事整个处理过程是一个大Span里面查数据库是一个子Span调用支付网关是另一个子Span更新缓存又是一个子Span。所有子Span共同组成一棵树这棵树就是一条Trace。每个Span身上挂着一批关键的元数据字段作用说明TraceId整条链路唯一标识一个Trace下所有Span共享同一个TraceId用于链路串联SpanId当前Span唯一标识每个Span自己独有的IDParentSpanId父Span标识根Span此字段为空StartTime / EndTime开始与结束时间戳计算延迟的基础精确到纳秒级别SpanKindSpan类型常见有SERVER、CLIENT、PRODUCER、CONSUMER、INTERNALAttributes键值对属性业务维度信息的载体比如订单号、用户IDEvents带时间戳的事件记录操作过程中的关键时刻如重试、降级、缓存未命中Status结束状态未设置、OK、ERROR 三种从生命周期的角度来说一个Span从创建开始经过“写入数据”阶段最后“结束”然后被SpanProcessor导出到后端。这里有一个新手很容易犯的错误Span结束之后再调set_attribute、add_event这些接口操作会被静默忽略数据不会出现在后端里。所以一定要在end()之前把该写的业务信息写进去。2.2 用属性、事件、状态把业务价值塞进Span光有调用层级的时间戳能做性能分析但做不了业务排障。出了问题的请求你往往想知道的是这是哪个用户的请求订单号是多少优惠券有没有生效支付金额对不对这些信息就得通过Span Attributes带上。我一般会在核心业务Span上固定写这几个维度大家可以根据自己的业务调整span.set_attribute(user.id, user_id) span.set_attribute(order.id, order_id) span.set_attribute(payment.amount, amount)在FastAPI的自动埋点里框架生成的HTTP Span已经内置了一大批标准属性包括HTTP方法、路由、状态码、客户端IP这些你额外要做的就是把业务字段补上去。Event适合用来记录“过程中发生了什么”。它的本质是一条带时间戳的注解。比如调用第三方支付网关超时后重试了一次span.add_event(payment.retry, {attempt: 1, reason: timeout})Status则是操作最终状态的结论。结合异常记录一个完整的手动埋点异常处理应该是这样try: result pay_gateway.confirm(order_id, amount) except Exception as exc: span.record_exception(exc) span.set_status(trace.Status(trace.StatusCode.ERROR, str(exc))) raise注意record_exception会把这个异常生成一个类型为exception的Event打到Span上包含异常类型、消息和堆栈但不会自动置Span为错误状态。两个步骤都要做既留下了现场快照又给链路打了错误标记后端的服务列表页才能正确反映错误率。3. Scope决定“当前正在做什么”的聚光灯3.1 ContextSpan之间传递信息的快递柜要理解Scope先得理解Context。OpenTelemetry里有一个全局Context对象本质上是一个KV存储它在异步框架里的传播是通过Python的ContextVars实现的。大家可以这样理解Context是当前协程身上背着的一个“快递柜”。柜子里放着一堆键值对其中最关键的一个键就是“当前激活的Span”。程序在任何位置通过trace.get_current_span()获取当前Span本质上是去这个快递柜里取那个键对应的值。FastAPI每个请求进来asyncio会给它单独复制一份Context快照。所以正常写的异步代码里Context天然是请求隔离的——A请求的Context不会自动跑到B请求里去。但一旦你用了线程池、进程池这些跨执行体的机制隔离就失效了后面第五节我会专门讲这个坑。3.2 Scope的本质激活窗口与上下文恢复接着讲Scope。Scope最准确的理解是一个“时间窗口”它表示某个Span在这段时间内被标记为当前上下文中的活跃Span。想象一个聚光灯。你站在舞台中央聚光灯打在你身上观众只看得见你这时候你做什么都很显眼。当你表演完退到一边聚光灯立刻跳回上一个演员身上。Scope干的就是这件事当一个Span被激活它就处于聚光灯下被移出Scope聚光灯就恢复给父Span。关键来了OpenTelemetry的Python API里提供了两个容易混淆的方法span tracer.start_span(manual_span) # 只创建不激活 with tracer.start_as_current_span(auto_span): # 创建并激活 do_something()start_span单纯创建了一个Span对象它不会注册到当前Context里所以你在操作内部再创建子Span它不会自动变成“当前操作”的父Span。更麻烦的是这个Span必须在结束的时候手动调用span.end()忘了调用就直接丢数据。start_as_current_span才是日常开发中真正要用的那个。它的with块负责两件事进入时激活Span并让它成为当前Span退出时结束这个Span并自动恢复之前那个Span继续作为当前活跃Span。3.3 Scope Manager与Context变量传播在OpenTelemetry底层Scope的创建与销毁是通过context.attach和context.detach来管理的。启动一个Scope时SDK会执行等价于attach的操作把新的Span写进Context同时换来一个tokenScope退出时拿着token做detach把Context恢复原状。这套机制从应用代码层面看就是上面那个with语句。但为什么我要单独提attach/detach因为排查问题的时候你会发现很多诡异的“上下文串线”“Span层级错乱”最终都能追溯到“该detach的地方没有detach”。最常见的场景就是异步回调里手动持有Scope没有释放或者把Scope对象塞进了某个共享变量。Scope的生命周期应该和它所在的代码块严格绑定用with就是最安全的姿势。另外要提醒一句start_as_current_span返回的上下文管理器对象本身不是Span你with它拿到的那个变量才是Span。这个细节写错的人不少尤其在写装饰器、异步回调的时候千万别把manager对象当成Span去设置Attribute那样数据会上到一个你看不见的“幽灵Span”上。4. 在FastAPI里落地从初始化到业务埋点4.1 初始化TracerProvider与Span导出器纸上谈兵结束下面进入实操。整个接入过程分三步先初始化TracerProvider再注册SpanProcessor然后给FastAPI应用装上自动埋点。初始化这一块常见的选择是把数据导到OpenTelemetry Collector再由Collector分发给后端的Jaeger、Zipkin或SkyWalking。这里用OTLP HTTP exporter做示例from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.sdk.resources import Resource, SERVICE_NAME from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter resource Resource.create({SERVICE_NAME: order-service}) provider TracerProvider(resourceresource) provider.add_span_processor( BatchSpanProcessor( OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces) ) ) trace.set_tracer_provider(provider)SERVICE_NAME这个Resource属性一定要设置它决定了后端界面上服务列表里你这条服务叫什么名字。很多新手忘记配置结果数据导过去之后服务名是空的排查半天找不到在哪看数据。BatchSpanProcessor和SimpleSpanProcessor的区别也值得说一句Batch是攒一批Span再异步导出对业务请求路径零阻塞适合生产环境Simple是每来一个Span立刻导出虽然实时性好但会在请求路径里插入一次全同步的IO测试环境玩玩可以生产慎用。4.2 自动埋点FastAPIInstrumentor一行接入FastAPI官方给了现成的自动埋点包用法朴素得让人怀疑是不是漏了什么from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor from fastapi import FastAPI app FastAPI() FastAPIInstrumentor.instrument_app(app)加完这一行FastAPI服务跑起来之后每个收到的HTTP请求都会自动生成一个Server类型的Span自动带上HTTP方法、路由模板、状态码、客户端IP这些标准属性。也就是说不用改业务代码你的服务就已经有了最基础的追踪能力请求进来了多长时间、返回什么状态码、是不是慢请求在链路后端一目了然。有个隐藏的机制值得注意自动埋点生成的HTTP Span称为“顶层Span”它其实挂在一个由instrumentation内部创建的root Span下面而不是凭空产生新的Trace。所以你在业务代码里手动创建的子Span会通过Scope的自动传播自然而然挂到这个请求对应的HTTP Span后面链路呈现出来的就是“HTTP请求 → 你的业务操作”这种两层级联结构。4.3 手动埋点给核心业务加上自定义Span自动埋点解决的是“HTTP层有没有问题”的感知但真正的业务逻辑在哪一步耗时、有没有失败还得靠手动埋点。手动埋点的核心工具是Tracer对象。Tracer代表一类埋点工具的命名空间你可以按业务域拆比如get_tracer(order.service.payment)和get_tracer(order.service.inventory)方便后端按模块过滤。支付回调的伪代码示例from opentelemetry import trace tracer trace.get_tracer(order.service.payment) def handle_payment_callback(order_id: str, amount: float): with tracer.start_as_current_span(payment.callback.handle) as span: span.set_attribute(order.id, order_id) span.set_attribute(payment.amount, amount) try: result pay_gateway.confirm(order_id, amount) span.set_attribute(payment.status, result.status) except Exception as exc: span.record_exception(exc) span.set_status(trace.Status(trace.StatusCode.ERROR, str(exc))) raise用with写法Scope的激活与销毁就是Python上下文管理器自带的语义不存在忘记释放的问题。嵌套场景再进一步如果回调处理里还需要查数据库、调外部接口那就再往里包一层with tracer.start_as_current_span(payment.callback.handle) as span: with tracer.start_as_current_span(db.order.update) as db_span: db_span.set_attribute(db.table, orders) update_order_status(order_id, paid)内层Span不需要手动指定父Span因为外层Span在Context里是激活的SDK会自动把新Span的ParentSpanId指到外层Span上。这正是Scope管理带来的便利你只管用上下文管理器嵌套父子关系自动建好。4.4 异步任务、后台任务与Scope传播FastAPI有一个高频异步场景需要特殊处理BackgroundTasks。它是FastAPI自带的后台任务机制可以在响应返回之后再继续跑一段逻辑比如发通知邮件、写操作日志。这里有一个很多人踩过的大坑BackgroundTasks在响应结束、HTTP Span结束之后才执行此时请求的Scope早已被清理你在后台任务里新建的Span并不会自动挂回原来的HTTP请求链路。解决思路是在任务提交时把当时的Context快照捕获并手工传递。利用contextvars.copy_context()import contextvars from fastapi import BackgroundTasks from opentelemetry import trace def send_notification(ctx, order_id: str): ctx.run(_send_notification_inner, order_id) def _send_notification_inner(order_id: str): with trace.get_tracer(order.service.notify).start_as_current_span(notification.send) as span: span.set_attribute(order.id, order_id) send_email(order_id) background_tasks.add_task(send_notification, contextvars.copy_context(), order_id)ctx.run会把捕获时的Context完整恢复到当前协程里再执行目标任务。这样后台任务里的手工Span就能拿到当时还在生效的TraceId和ParentSpanId链路依然连贯。这个模式同样适用于queue、consumer这些异步场景核心思想就一句话跨执行体必须手工传递Context快照。5. 高频踩坑与排查技巧我替你先踩过的那些坑5.1 Span上下文串线A请求打上了B请求的标签现象很诡异后端看到某条Trace里出现了两个不相关的业务操作而且这条Trace的TraceId明明来自请求ASpan的属性里却出现了请求B的订单号、用户ID。排查方向先看有没有手写attach/detach没成对再看是不是把全局变量当成了局部缓存。分布式追踪的Context靠ContextVars传播它的生命周期和协程绑定。如果你在某个模块里用模块级变量保存了“上一个请求的Span”或者复用了同一个Scope对象那A请求结束后B请求很可能读到A留下的脏上下文。经验法则不要在单例对象、模块级变量、类属性里存任何跟请求相关的Span引用。Span和Scope必须活在你当前操作的局部作用域里。5.2 Span没有父子关系全是根节点后端界面上看到的Span全都没连在一起每个Span单独一条链路TraceId各归各。最典型的操作是用了tracer.start_span()而没用start_as_current_span()。start_span只负责生产一个Span对象它既不会激活到当前Context也不会被后续子Span自动识别为父Span。结果就是你创建了一堆孤立节点除了拥有相同TraceId之外没有任何结构逻辑。如果因为某些特殊场景非用start_span不可记得在创建子Span时显式传parent参数并且自己管理生命周期span tracer.start_span(parent) child tracer.start_span(child, parentspan.get_context()) span.end() child.end()但从工程实践角度我建议代码里统一使用start_as_current_span让SDK替你管好大部分事情只在极少数需要控制话场景下才手工管理。5.3 Span不导出缓冲积压与进程退出代码看起来都写了但后端一直收不到新数据。先想两个原因第一如果是BatchSpanProcessor数据是攒着异步导出的进程退出前必须调用provider.shutdown()把缓冲区的Span刷出去。FastAPI服务优雅停机时如果没做这个动作最后一批Span会直接消失。Uvicorn的on_shutdown钩子可以把shutdown逻辑挂上去。第二如果是生产流量下的持续积压要考虑BatchSpanProcessor的导出线程是不是被阻塞了。Collector地址不通、网络抖动会导致Span在缓冲区堆积积累到阈值直接丢弃。排查时先看导出器日志再用tracer.start_as_current_span之外的方式做一次最小化导出验证。5.4 线程池里上下文丢了什么都查不到FastAPI服务里用了ThreadPoolExecutor线程池内部执行的函数里创建的Span总是挂不回去。原因前面已经埋下伏笔ContextVars的传播只在协程继承链和Task继承链上自动发生线程池不会复制发起线程的上下文。解决方案就是在提交任务前捕获Context快照并随任务传递代码见4.4小节的模式。同样的道理只要跨了执行体线程、进程、新的Task但没走asyncio.create_task继承机制就必须手工传Context。常见问题速查现象原因解决方案多个请求的Span混在一起Context泄漏Scope未正确退出检查手动attach/detach避免全局变量存Span新Span没有父节点用了start_span而不是start_as_current_span统一用start_as_current_span进程退出时Span丢失Batch导出缓冲未刷出优雅停机时调用provider.shutdown()线程池内Span链路断裂ContextVars未跨线程传播用contextvars.copy_context()快照并随任务传递Span结束前数据丢失end()后还在写属性所有set_attribute/add_event放在end之前5.5 埋点无用武之地先把自动埋点跑起来再谈优化还有一类问题不是技术坑是心想上的坑刚接上分布式追踪就想把所有业务逻辑都埋一遍点结果接口路径上加了十几个手工Span后端界面刷出来一团乱麻反而看不清楚主干在哪。我的经验是分阶段来。第一步先只上FastAPIInstrumentor自动埋点让每条请求天然带上HTTP层Span熟悉链路后端的基本操作。第二步挑两三个最核心的链路比如支付回调、下单主流程手工埋点验证嵌套Span的父子关系和业务属性。第三步再把慢查询、外部依赖调用这些最容易成为瓶颈的点补上。每一步都能在链路后端看到明确的数据变化再考虑扩大埋点范围。写在最后的一点体会做分布式追踪这几年我最大的感受是它改变的不是排查速度而是排查问题的思维方式——从“哪台机器可能有问题”变成“这条链路到底经历了什么”。Span和Scope是两个极其朴素的概念一个是数据容器一个是活跃窗口但把它们放在FastAPI这种异步模型里加上线程池、后台任务这些执行体的切换细节就会变得异常丰富。最后分享一个实战中非常有用的小习惯在每个核心业务的Span上固定加上版本号attribute比如span.set_attribute(deploy.version, v1.2.0)。服务发布后如果出现延迟异常直接在链路后端按版本号过滤能立刻看出是不是新版本代码引入的回归问题。这个技巧在快节奏迭代的团队里救过我太多次。