Opik Python SDK用 opik_context.get_current_span_data 在 track 追踪函数中读取当前 Span 数据【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本文围绕 Opik Python SDK 的 API 文档页get_current_span_data展开讲解如何在track装饰器包裹的函数内部获取当前正在执行的 Span 上下文数据SpanData包括其返回结构、返回None的边界条件、底层基于contextvars的 span 栈实现原理以及在 Guardrails、分布式追踪等真实场景中的典型用法。读完本文你可以掌握在任意被追踪代码中自下而上读取 trace_id、span id、父 span 关系、model/usage 等字段的方法并理解它与get_current_trace_data、update_current_span、get_distributed_trace_headers等配套函数的调用关系。文档定位一个 API 参考页背后是完整的上下文模块仓库中的关联文档 get_current_span_data.rst 本身是一页 Sphinxautofunction生成的 API 参考页仅一行核心指令.. autofunction:: opik.opik_context.get_current_span_data它指向 SDK 中真实实现的 opik_context.py 模块里的get_current_span_data函数。该模块所属的opik_context子包整体介绍如何从被追踪函数内部访问当前 span 和 trace 数据完整用法示例见 opik_context/index.rstfrom opik import opik_context, track track def my_function(): # Get the current span data span_data opik_context.get_current_span_data() print(span_data) # Get the current trace data trace_data opik_context.get_current_trace_data() print(trace_data) # Update the current span metadata opik_context.update_current_span(metadata{my_key: my_value}) # Update the current trace tags opik_context.update_current_trace(tags[my_tag])下面逐层拆解get_current_span_data的签名、行为与底层机制。函数签名与核心行为get_current_span_data的实现位于 opik_context.pydef get_current_span_data() - Optional[span.SpanData]: Returns the current span created by track() decorator or None if no span was found. span_data context_storage.top_span_data() if span_data is None: return None return span.SpanData(**span_data.__dict__)要点逐条说明无参数调用它不接收任何参数完全依赖当前执行上下文来定位 span。也就是说调用方必须位于由track装饰器或等价的 span context manager创建的追踪函数内部。返回值类型Optional[span.SpanData]。在追踪上下文内返回SpanData对象若上下文中不存在任何 span返回None而不是抛异常。这与同模块的update_current_span、get_distributed_trace_headers上下文为空时抛出OpikException(There is no span in the context.)见 opik_context.py形成明确对比读取语义宽容写入/派生语义严格。返回的是副本实现通过span.SpanData(**span_data.__dict__)用当前栈顶 span 的全部属性重新构造了一个新的SpanData实例。从源码结构看这是把上下文栈中维护的内部对象拷贝出来交给调用方避免业务代码在函数执行过程中意外改动栈内状态__dict__展开属于浅拷贝嵌套的 metadata 等字典仍与内部对象共享引用深度隔离并非设计目标。返回的 SpanData 结构有哪些字段SpanData定义于 span_data.py继承自 observation_data.py 的ObservationData。字段分为两组SpanData 自有字段字段类型说明trace_idstr所属 trace 的 idSpanData 的必填字段idstr当前 span 的 id默认由helpers.generate_id自动生成parent_span_idOptional[str]父 span 的 id根 span 为NonetypeSpanTypespan 类型默认generalLLM 调用为llmusageOptional[Dict[str, Any] \| OpikUsage]token 用量数据modelOptional[str]所用 LLM 名称providerOptional[str \| LLMProvider]LLM 提供方total_costOptional[float]本次调用成本USDObservationData 基类通用字段TraceData与SpanData共享name、start_time、end_time、metadata、input、output、tags、feedback_scores、project_name、error_info、attachments、source默认sdk、environment。拿到span_data后一个典型用法是提取关键标识用于日志关联或跨系统透传from opik import opik_context, track track def process_user_query(query: str) - str: span_data opik_context.get_current_span_data() if span_data is not None: # 将 trace/span 标识写入业务日志便于与 Opik UI 中的 trace 对齐 logger.info( processing query, trace_id%s, span_id%s, project%s, span_data.trace_id, span_data.id, span_data.project_name, ) return query.upper()边界条件何时返回 None返回None的场景包括在追踪上下文外调用顶层脚本、未被track覆盖的普通函数中直接调用此时 span 栈为空。追踪被运行时配置禁用SDK 有 tracing 运行时开关tracing_runtime_config.is_tracing_active()见 opik_context.py 中update_current_span的短路逻辑。从源码结构看禁用追踪时 span 不会被压入上下文栈get_current_span_data自然返回None。SDK 的单元测试也专门覆盖了这一路径例如 test_track_disabled_mode.py 验证了 disabled 模式下上下文 API 的表现。因此生产代码中的稳健写法是先判空再使用span_data opik_context.get_current_span_data() if span_data is None: return # 或降级到本地日志底层原理基于 contextvars 的不可变 span 栈get_current_span_data的数据来源是 context_storage.py 中的OpikContextStorage。track进入被追踪函数时会add_span_data压栈函数退出时pop_span_data出栈get_current_span_data内部调用的top_span_data()直接取栈顶元素def top_span_data(self) - Optional[span.SpanData]: if self.span_data_stack_empty(): return None stack self._spans_data_stack_context.get() return stack[-1]该实现有两个值得注意的设计点上下文隔离span 栈存放在contextvars.ContextVar中且刻意使用不可变 tuple并以取旧值、构造新值再 set的模式更新见 context_storage.py 类注释与 add_span_data。这保证了多线程、asyncio 并发任务之间各自的 span 栈互不污染——当前 span是相对于当前执行上下文而言的而不是进程全局单例。嵌套 track 的语义track嵌套调用时内层 span 会压到栈顶因此内层函数里get_current_span_data拿到的是最内层那个 span其parent_span_id指向外层 span 的idtrace_id保持一致。这一父链关系正是 Opik 在 UI 中渲染嵌套 span 树的基础。同一文件还提供了防御性工具trim_span_data_stack_to_certain_spancontext_storage.py供回调式集成如 LangChain callback在可能漏掉 pop 操作时按已知 span id 截断栈避免悬挂 span污染后续上下文——这也从侧面说明 span 栈模型是 SDK 追踪体系的核心数据结构。SDK 内部真实调用场景get_current_span_data不只是给用户用的公共 APISDK 自身也大量依赖它。在 guardrail.py 中Guardrail 执行时通过current_span get_current_span_data()找到当前 span把守卫的评估结果通过/拦截、分数挂载到正在执行的追踪数据上从而让拦截行为出现在 Opik 对应 trace 的 span 详情里。类似地get_current_trace_data的调用点散布于 llm_judge.py、ragas_metric.py 等评估与集成模块中用于把自动评估分数回写到当前 trace。与同模块其他函数的协作关系opik_context模块的完整 API 面见 opik_context.py 的__all__可以按读取 / 更新 / 派生三类理解get_current_span_data的位置函数类别无 span 时的行为典型用途get_current_span_data()读取返回None获取当前 span 的 id、trace_id、父子关系get_current_trace_data()读取返回None获取当前 trace 的 id 与字段update_current_span(...)更新抛OpikException在追踪函数内补写 metadata、output、feedback_scores 等update_current_trace(...)更新抛OpikException补写 trace 级字段get_distributed_trace_headers()派生抛OpikException拿到{opik_trace_id, opik_parent_span_id}字典透传给远程节点实现跨进程追踪一个组合场景是分布式追踪index.rst 给出了直接取分布式头的示例若你需要更细粒度地拼装 header也可以先span_data opik_context.get_current_span_data()再用span_data.trace_id与span_data.id构造等价内容——get_distributed_trace_headers 内部正是这样做的。验证手段该 API 的行为有对应测试可查证test_span_context_manager.py验证track/ span context manager 内get_current_span_data返回的 span 数据trace_id、parent 关系等符合预期test_track_disabled_mode.py覆盖追踪禁用时的上下文行为test_distributed_headers_context_manager.py覆盖基于当前 span 的分布式头生成端到端层面test_tracing.py 等 E2E 用例确认了这些字段最终落库后可在检索结果中被读取。小结opik_context.get_current_span_data是 Opik Python SDK 中追踪函数自省的入口它以零参数返回当前track上下文栈顶的SpanData副本无上下文时安静地返回None其背后是contextvars 不可变 tuple 实现的线程/任务安全 span 栈。掌握它之后你可以在业务代码里把 trace_id / span_id 写入日志系统做跨系统关联在自定义 Guardrail 或评估逻辑中把结果挂回当前 span并在此基础上用get_distributed_trace_headers把追踪跨进程传递。如需创建新的 trace/span 而非读取现有上下文请参阅 SDK 的 context manager 文档context_manager/index.rst 所指向的目录。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Opik Python SDK：用 opik_context.get_current_span_data 在 track 追踪函数中读取当前 Span 数据
Opik Python SDK用 opik_context.get_current_span_data 在 track 追踪函数中读取当前 Span 数据【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本文围绕 Opik Python SDK 的 API 文档页get_current_span_data展开讲解如何在track装饰器包裹的函数内部获取当前正在执行的 Span 上下文数据SpanData包括其返回结构、返回None的边界条件、底层基于contextvars的 span 栈实现原理以及在 Guardrails、分布式追踪等真实场景中的典型用法。读完本文你可以掌握在任意被追踪代码中自下而上读取 trace_id、span id、父 span 关系、model/usage 等字段的方法并理解它与get_current_trace_data、update_current_span、get_distributed_trace_headers等配套函数的调用关系。文档定位一个 API 参考页背后是完整的上下文模块仓库中的关联文档 get_current_span_data.rst 本身是一页 Sphinxautofunction生成的 API 参考页仅一行核心指令.. autofunction:: opik.opik_context.get_current_span_data它指向 SDK 中真实实现的 opik_context.py 模块里的get_current_span_data函数。该模块所属的opik_context子包整体介绍如何从被追踪函数内部访问当前 span 和 trace 数据完整用法示例见 opik_context/index.rstfrom opik import opik_context, track track def my_function(): # Get the current span data span_data opik_context.get_current_span_data() print(span_data) # Get the current trace data trace_data opik_context.get_current_trace_data() print(trace_data) # Update the current span metadata opik_context.update_current_span(metadata{my_key: my_value}) # Update the current trace tags opik_context.update_current_trace(tags[my_tag])下面逐层拆解get_current_span_data的签名、行为与底层机制。函数签名与核心行为get_current_span_data的实现位于 opik_context.pydef get_current_span_data() - Optional[span.SpanData]: Returns the current span created by track() decorator or None if no span was found. span_data context_storage.top_span_data() if span_data is None: return None return span.SpanData(**span_data.__dict__)要点逐条说明无参数调用它不接收任何参数完全依赖当前执行上下文来定位 span。也就是说调用方必须位于由track装饰器或等价的 span context manager创建的追踪函数内部。返回值类型Optional[span.SpanData]。在追踪上下文内返回SpanData对象若上下文中不存在任何 span返回None而不是抛异常。这与同模块的update_current_span、get_distributed_trace_headers上下文为空时抛出OpikException(There is no span in the context.)见 opik_context.py形成明确对比读取语义宽容写入/派生语义严格。返回的是副本实现通过span.SpanData(**span_data.__dict__)用当前栈顶 span 的全部属性重新构造了一个新的SpanData实例。从源码结构看这是把上下文栈中维护的内部对象拷贝出来交给调用方避免业务代码在函数执行过程中意外改动栈内状态__dict__展开属于浅拷贝嵌套的 metadata 等字典仍与内部对象共享引用深度隔离并非设计目标。返回的 SpanData 结构有哪些字段SpanData定义于 span_data.py继承自 observation_data.py 的ObservationData。字段分为两组SpanData 自有字段字段类型说明trace_idstr所属 trace 的 idSpanData 的必填字段idstr当前 span 的 id默认由helpers.generate_id自动生成parent_span_idOptional[str]父 span 的 id根 span 为NonetypeSpanTypespan 类型默认generalLLM 调用为llmusageOptional[Dict[str, Any] \| OpikUsage]token 用量数据modelOptional[str]所用 LLM 名称providerOptional[str \| LLMProvider]LLM 提供方total_costOptional[float]本次调用成本USDObservationData 基类通用字段TraceData与SpanData共享name、start_time、end_time、metadata、input、output、tags、feedback_scores、project_name、error_info、attachments、source默认sdk、environment。拿到span_data后一个典型用法是提取关键标识用于日志关联或跨系统透传from opik import opik_context, track track def process_user_query(query: str) - str: span_data opik_context.get_current_span_data() if span_data is not None: # 将 trace/span 标识写入业务日志便于与 Opik UI 中的 trace 对齐 logger.info( processing query, trace_id%s, span_id%s, project%s, span_data.trace_id, span_data.id, span_data.project_name, ) return query.upper()边界条件何时返回 None返回None的场景包括在追踪上下文外调用顶层脚本、未被track覆盖的普通函数中直接调用此时 span 栈为空。追踪被运行时配置禁用SDK 有 tracing 运行时开关tracing_runtime_config.is_tracing_active()见 opik_context.py 中update_current_span的短路逻辑。从源码结构看禁用追踪时 span 不会被压入上下文栈get_current_span_data自然返回None。SDK 的单元测试也专门覆盖了这一路径例如 test_track_disabled_mode.py 验证了 disabled 模式下上下文 API 的表现。因此生产代码中的稳健写法是先判空再使用span_data opik_context.get_current_span_data() if span_data is None: return # 或降级到本地日志底层原理基于 contextvars 的不可变 span 栈get_current_span_data的数据来源是 context_storage.py 中的OpikContextStorage。track进入被追踪函数时会add_span_data压栈函数退出时pop_span_data出栈get_current_span_data内部调用的top_span_data()直接取栈顶元素def top_span_data(self) - Optional[span.SpanData]: if self.span_data_stack_empty(): return None stack self._spans_data_stack_context.get() return stack[-1]该实现有两个值得注意的设计点上下文隔离span 栈存放在contextvars.ContextVar中且刻意使用不可变 tuple并以取旧值、构造新值再 set的模式更新见 context_storage.py 类注释与 add_span_data。这保证了多线程、asyncio 并发任务之间各自的 span 栈互不污染——当前 span是相对于当前执行上下文而言的而不是进程全局单例。嵌套 track 的语义track嵌套调用时内层 span 会压到栈顶因此内层函数里get_current_span_data拿到的是最内层那个 span其parent_span_id指向外层 span 的idtrace_id保持一致。这一父链关系正是 Opik 在 UI 中渲染嵌套 span 树的基础。同一文件还提供了防御性工具trim_span_data_stack_to_certain_spancontext_storage.py供回调式集成如 LangChain callback在可能漏掉 pop 操作时按已知 span id 截断栈避免悬挂 span污染后续上下文——这也从侧面说明 span 栈模型是 SDK 追踪体系的核心数据结构。SDK 内部真实调用场景get_current_span_data不只是给用户用的公共 APISDK 自身也大量依赖它。在 guardrail.py 中Guardrail 执行时通过current_span get_current_span_data()找到当前 span把守卫的评估结果通过/拦截、分数挂载到正在执行的追踪数据上从而让拦截行为出现在 Opik 对应 trace 的 span 详情里。类似地get_current_trace_data的调用点散布于 llm_judge.py、ragas_metric.py 等评估与集成模块中用于把自动评估分数回写到当前 trace。与同模块其他函数的协作关系opik_context模块的完整 API 面见 opik_context.py 的__all__可以按读取 / 更新 / 派生三类理解get_current_span_data的位置函数类别无 span 时的行为典型用途get_current_span_data()读取返回None获取当前 span 的 id、trace_id、父子关系get_current_trace_data()读取返回None获取当前 trace 的 id 与字段update_current_span(...)更新抛OpikException在追踪函数内补写 metadata、output、feedback_scores 等update_current_trace(...)更新抛OpikException补写 trace 级字段get_distributed_trace_headers()派生抛OpikException拿到{opik_trace_id, opik_parent_span_id}字典透传给远程节点实现跨进程追踪一个组合场景是分布式追踪index.rst 给出了直接取分布式头的示例若你需要更细粒度地拼装 header也可以先span_data opik_context.get_current_span_data()再用span_data.trace_id与span_data.id构造等价内容——get_distributed_trace_headers 内部正是这样做的。验证手段该 API 的行为有对应测试可查证test_span_context_manager.py验证track/ span context manager 内get_current_span_data返回的 span 数据trace_id、parent 关系等符合预期test_track_disabled_mode.py覆盖追踪禁用时的上下文行为test_distributed_headers_context_manager.py覆盖基于当前 span 的分布式头生成端到端层面test_tracing.py 等 E2E 用例确认了这些字段最终落库后可在检索结果中被读取。小结opik_context.get_current_span_data是 Opik Python SDK 中追踪函数自省的入口它以零参数返回当前track上下文栈顶的SpanData副本无上下文时安静地返回None其背后是contextvars 不可变 tuple 实现的线程/任务安全 span 栈。掌握它之后你可以在业务代码里把 trace_id / span_id 写入日志系统做跨系统关联在自定义 Guardrail 或评估逻辑中把结果挂回当前 span并在此基础上用get_distributed_trace_headers把追踪跨进程传递。如需创建新的 trace/span 而非读取现有上下文请参阅 SDK 的 context manager 文档context_manager/index.rst 所指向的目录。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考