Arize Phoenix 追踪插件

by-framework-trace-phoenix 提供了基于 OpenTelemetry 标准的追踪支持，并特别适配了 Arize Phoenix 作为后端。

安装

你可以通过 pip 安装此插件及其核心埋点扩展：

pip install by-framework-trace-phoenix

如果是为了给 LangGraph 或 LangChain 开启自动埋点，建议安装相关的 Extras：

# 同时安装常用的自动埋点库
pip install "by-framework-langgraph[phoenix]"

配置

插件通过环境变量进行配置。

环境变量	说明	示例
PHOENIX_COLLECTOR_ENDPOINT	Phoenix 收集器地址	http://localhost:4317 或 http://localhost:4318
PHOENIX_PROJECT_NAME	项目名称	my-agent-project
BYAI_PHOENIX_ENABLED	是否启用	true 或 false

功能特性

• 标准驱动：完全基于 OpenTelemetry Trace 对象。
• 确定性 ID：自动将框架的 trace_id 转换为 OTEL 的 TraceId，确保跨系统数据对齐。
• 自动插桩：如果安装了相关的 openinference 埋点库，插件在启动时会自动补齐 LangChain 和 OpenAI 的插桩，即使这些库在插件启动前已被导入。
• 分布式上下文注入：自动在下游调用中注入 Trace Context 头部信息。

验证

1. 启动本地 Phoenix 实例：

   python -m phoenix.server.main serve
   

2. 启动配置好环境变量的 Worker。
3. 运行任务后，访问 http://localhost:6006。
4. 你将在 "Projects" 列表中看到该项目及其下方的 Trace 树。

LangGraph 集成

当启用该插件后，LangGraphAdapter 会自动关联当前的 OTEL 上下文。这意味着你在 LangGraph 内部发起的 LLM 调用（由 openinference 捕获）将作为 by-framework 任务子节点（Span）展现。