Apache Airflow common.ai 提供程序 OpenTelemetry 追踪实战：让 LLM 算子发出可关联的 GenAI Span-北京尧图网络

Apache Airflow common.ai 提供程序 OpenTelemetry 追踪实战让 LLM 算子发出可关联的 GenAI Span【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本文基于 Apache Airflow 仓库中apache-airflow-providers-common-ai提供程序的官方文档与源码讲解如何为 pydantic-ai Agent 开启原生 OpenTelemetryOTelGenAI 追踪从核心原理复用 Airflow 核心追踪的 TracerProvider、自动与任务 Span 关联到完整的配置步骤[traces] otel_on、[common.ai] otel_export_enabled、OTEL_EXPORTER_OTLP_*环境变量、内容捕获开关capture_content的安全边界以及 pydantic-ai 2.x 下 token 用量属性命名gen_ai.usage.*与gen_ai.aggregated_usage.*的兼容要点。读完本文你能够将AgentOperator、task.agent、task.llm等 LLM 算子产生的 Agent 运行、模型调用、工具调用 Span 准确导出到 Jaeger、Tempo、Grafana 或 OTLP Collector 等后端并与对应的 DAG 运行/任务实例关联分析。一、功能定位为 common.ai 提供程序的每个 Agent 运行发出 GenAI Spanpydantic-ai 自带原生 OpenTelemetry 插桩能力可以为每一次 Agent 运行agent run、模型调用model call、工具调用tool call发出遵循 OpenTelemetry GenAI 语义规范的 Span。common.ai 提供程序apache-airflow-providers-common-ai做的事情是在构建每个 Agent 时自动打开这一插桩并将 Span 路由到 Airflow 已经在用的 OTel 导出器上让这些 GenAI Span 直接出现在你的部署所连接的追踪后端中Jaeger、Tempo、Grafana、Phoenix、Langfuse、OTLP Collector 等并与产生它们的任务实例task instance自动关联。这一能力覆盖该提供程序的全部 LLM 算子包括AgentOperator、task.agent/task.llm装饰器以及 SQL / 分支branch/ 文件分析file analysis/ 模式对比schema compare算子——因为它们的 Agent 全部通过 PydanticAIHook.create_agent 这一个入口构建插桩逻辑只需挂在这一处即可全量生效。二、工作原理零额外基础设施、自动关联、内容默认不导出2.1 不配置自己的 Exporter 或 TracerProvider提供程序不自行配置任何 Exporter 或 TracerProvider而是复用 Airflow 核心追踪core tracing在 worker 进程中安装的全局 SDKTracerProvider因此 GenAI Span 与 Airflow 自身 Span 共享同一套已在[traces]段 / 标准OTEL_EXPORTER_OTLP_*环境变量下配置好的导出器与端点。若 worker 进程未开启核心追踪则不会发出任何 GenAI Span。从源码结构看这一设计集中在 observability.py 模块中模块 docstring 明确说明其定位把 pydantic-ai 的 GenAI Span “指向 Airflow 现有的 OpenTelemetry 导出器使其流转到部署已经在跑的任意 OTLP 后端并嵌套在 worker 的任务 Span 之下”_live_tracer_provider()通过trace.get_tracer_provider()获取全局 provider只有当它确为opentelemetry.sdk.trace.TracerProvider实例时才返回否则OpenTelemetry SDK 未安装、核心追踪未安装 provider只剩 API 的 no-op 代理返回None从而从根源上避免发出孤儿 Spangenai_instrumentation_settings()是两个开关otel_export_enabled、worker 内是否有存活 provider都满足时才构建 pydantic-ai 的InstrumentationSettings返回任一不满足则返回NoneAgent 保持未插桩状态追踪关闭时零开销。该函数中有两个值得注意的实现细节语义规范版本被显式固定_SEMCONV_VERSION: Literal[5] 5observability.py#L43-L49。注释说明固定版本号是为了防止 pydantic-ai 默认值变化在提供程序版本之间静默改变 Span/属性格式2.x 中格式 2-4 仍可用但已弃用。懒加载导入pydantic_ai.models.instrumented子模块在函数体内按需导入observability.py#L97-L101。因为该模块会在每次构建 Agent 时被 hook 导入而追踪关闭是常见路径懒加载可以避免这一成本。构建出的设置对象为InstrumentationSettings( version_SEMCONV_VERSION, # 固定为 5 include_content_capture_content(), # 由 [common.ai] capture_content 控制默认 False include_binary_contentFalse, # 二进制内容始终不导出 tracer_providerprovider, # 复用 worker 中核心的 SDK provider )2.2 与任务 Span 的关联是自动的worker 会在算子运行之前打开任务 Spantask spanAgent 的 Span 自动嵌套在其下继承任务的trace_id与airflow.*属性dag id、run id、task id、try number、map index。自动重试会复用任务实例持久化的追踪上下文因此所有尝试共享同一条 trace在 trace 中表现为重复的任务运行 Span用try number区分只有手动 clear 或 rerun 才会重新生成上下文、开启新 trace。在 hooks/pydantic_ai.py 的 create_agent 中可以看到插桩的挂载点pydantic-ai 2.x 已不再把instrument作为Agent()/Agent.from_file()的构造参数改为通过agent.instrument属性设置因此 hook 会先把调用方显式传入的instrument参数从agent_kwargs中弹出若调用方自己传了则调用方的值优先于提供程序的自动插桩否则才调用genai_instrumentation_settings()并赋给agent.instrumentcaller_instrument agent_kwargs.pop(instrument, _UNSET) # ... 构建 Agentfrom_file 或 Agent(...) ... if caller_instrument is not _UNSET: agent.instrument caller_instrument else: settings genai_instrumentation_settings() if settings is not None: agent.instrument settings2.3 内容默认不导出默认情况下 Span 只记录 token 数、模型 id、延迟、工具名与结束原因finish reason从不导出提示词与补全文本除非显式选择开启见第四节。注意pydantic-ai 2.x 的 token 用量命名变化在 pydantic-ai 2.x 中agent-run Span 将 token 用量报告在gen_ai.aggregated_usage.*之下而每次模型调用model call的 Span 仍保留gen_ai.usage.*。这样做的目的是避免在后端对“父 Span 与其子 Span 求和”时重复计数。如果你的看板或告警是从gen_ai.usage.*读取 run 级 token 用量应切换到gen_ai.aggregated_usage.*。这一拆分在单元测试中被显式断言保护tests/unit/common/ai/test_observability.py端到端测试TestEndToEndSpanEmission通过 hook 构建真实 Agent、用一个模拟的“worker 任务父 Span”包裹运行然后断言gen_ai.usage.input_tokens与gen_ai.aggregated_usage.input_tokens都存在、所有 GenAI Span 与父 Span 共享trace_id、且提示词文本在关闭捕获时绝不泄漏。三、启用步骤3.1 配置文件开启核心追踪提供程序开关在airflow.cfg中同时启用核心追踪和提供程序选项[traces] otel_on True [common.ai] otel_export_enabled True其中[traces] otel_on是 Airflow 核心配置用于向 OpenTelemetry Collector 发送 Airflow 自身的 trace该选项自 2.10.0 引入见 config.yml 中traces段定义它决定了 worker 进程里是否安装了真实的 SDKTracerProvider——这是 GenAI Span 能否发出的前提[common.ai] otel_export_enabled由提供程序在 0.4.0 版本引入provider.yaml默认False默认关闭保证“安装提供程序本身绝不会在未选择的情况下开始发送 Span”。3.2 用标准 OpenTelemetry 环境变量配置导出目标导出器的目标地址只通过标准 OTel 环境变量配置。核心追踪默认使用 OTLP/gRPC 导出器若你要指向 OTLP/HTTP 端点端口 4318、/v1/traces路径还需显式选择 HTTP 导出器# 核心追踪默认使用 OTLP/gRPC 导出器。 # 若使用 OTLP/HTTP 端点4318 端口、/v1/traces 路径请同时选择 HTTP 导出器 export OTEL_TRACES_EXPORTERotlp_proto_http export OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://otel-collector:4318/v1/traces这与 Airflow 核心的演进方向一致[traces]段中项目专属的端点配置项如otel_host已在 3.2.0 起弃用配置应“完全通过标准 OpenTelemetry 环境变量完成”见 config.yml 中的弃用说明。完整的提供程序选项列表可参见 configurations-ref.rst。四、捕获提示词与补全文本capture_content及其安全边界默认 Span 不携带任何消息文本。如果需要在 GenAI Span 上同时记录模型输入与输出gen_ai.input.messages/gen_ai.output.messages设置[common.ai] capture_content True安全警告原文档的重要告诫务必理解开启capture_content后提示词、补全文本和工具 IO 会不做任何脱敏地导出到你的追踪后端。Airflow 的密钥掩码secret masking作用于日志和渲染后的模板字段不作用于 OpenTelemetry Span 属性因此它不会清洗这些内容。请仅在可信环境中为调试目的开启此选项。且该选项只有在otel_export_enabled为True时才有效果。源码层面这一语义对应InstrumentationSettings的两个字段include_content_capture_content()默认False读取[common.ai] capture_content版本 0.4.0 引入默认False与恒为False的include_binary_content——即便开启文本捕获二进制内容也永远不会被导出测试用例test_capture_content_opt_in_enables_content显式验证了这一点。端到端测试test_capture_content_includes_prompt_text则用一枚“特征提示词”验证开启后该文本确实出现在导出的 Span 属性中形成正反两面的行为基线。五、验证与源码/测试索引建议按以下顺序在仓库中核对本主题的关键实现便于建立对行为的信心关注点路径插桩设置构建、provider 探测、语义规范版本固定providers/common/ai/src/airflow/providers/common/ai/observability.pycreate_agent中agent.instrument的挂载与调用方覆盖逻辑providers/common/ai/src/airflow/providers/common/ai/hooks/pydantic_ai.py配置项otel_export_enabled/capture_content的官方定义含默认值、版本、说明providers/common/ai/provider.yaml开关判定、Span 嵌套、token 属性命名、内容泄漏防护的单元测试providers/common/ai/tests/unit/common/ai/test_observability.pyhook 侧genai_instrumentation_settings的调用点测试providers/common/ai/tests/unit/common/ai/hooks/test_pydantic_ai.py核心[traces]段配置定义airflow-core/src/airflow/config_templates/config.yml提供程序完整配置参考providers/common/ai/docs/configurations-ref.rst六、小结common.ai 提供程序的 OTel 追踪设计有三个核心特征值得记住零新增基础设施不建自己的导出链路完全复用核心追踪的TracerProvider与OTEL_EXPORTER_OTLP_*配置两个开关[traces] otel_on[common.ai] otel_export_enabled任一缺失即静默无 Span关联自动化GenAI Span 自动嵌套在 worker 任务 Span 下并继承airflow.*属性重试复用持久化的 trace 上下文同一次逻辑执行的所有尝试落在同一条 trace 上内容最小化原则默认只导出 token 数、模型 id、延迟、工具名与结束原因capture_content是唯一的文本导出开关且明确不受 Airflow 密钥掩码保护仅限可信环境调试使用。另外如果你基于 pydantic-ai 2.x 构建 token 用量看板请确认读取的是gen_ai.aggregated_usage.*run 级聚合而非gen_ai.usage.*单次模型调用级以免跨 Span 求和造成双重计数。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Apache Airflow common.ai 提供程序 OpenTelemetry 追踪实战：让 LLM 算子发出可关联的 GenAI Span

相关推荐

PrimeVue Timeline 组件完全指南：事件流可视化、对齐布局与深度定制

微信小程序社群人脉工具：群二维码采集与流量主变现全解析

集体好奇心如何提升团队协作与创新效率

更多资讯

解决Sangfor PWE残留：从服务权限失败到目录无法粉碎的彻底删除

ollama+openclaw本地AI助手部署与优化指南

基于.NET Framework的远程桌面开发：架构、协议与优化实践

HagiCode混合架构与PP协议加速技术解析

Cloudcart 自动化实战：在 awesome-codex-skills 中通过 Rube MCP 驱动 Cloudcart 工作流

从SVG打地鼠到实战进阶：坐标、路径与性能优化全解析

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？