phoenix-tracing

Phoenix 跟踪

在 Phoenix 中使用 OpenInference 跟踪对 LLM 应用进行埋点的完整指南。包含涵盖设置、埋点、Span 类型和生产环境部署的参考文件。

适用场景

在以下情况下请参考这些指南：

• 设置 Phoenix 跟踪（Python 或 TypeScript）
• 为 LLM 操作创建自定义 Span
• 按照 OpenInference 约定添加属性
• 将跟踪部署到生产环境
• 查询和分析跟踪数据

参考类别

优先级	类别	描述	前缀
1	设置	安装和配置	setup-*
2	埋点	自动和手动跟踪	instrumentation-*
3	Span 类型	9 种 Span 类型及其属性	span-*
4	组织方式	项目和会话	projects-*、sessions-*
5	丰富数据	自定义元数据	metadata-*
6	生产环境	批处理、脱敏	production-*
7	反馈	标注和评估	annotations-*

快速参考

1. 设置（从这里开始）

• setup-python - 安装 arize-phoenix-otel，配置端点
• setup-typescript - 安装 @arizeai/phoenix-otel，配置端点

2. 埋点

• instrumentation-auto-python - 自动为 OpenAI、LangChain 等添加埋点（也涵盖 OTel GenAI 原生埋点）
• instrumentation-auto-typescript - 自动为受支持的框架添加埋点
• instrumentation-manual-python - 使用装饰器创建自定义 Span
• instrumentation-manual-typescript - 使用包装器创建自定义 Span
• instrumentation-atif-python - 导入 ATIF Agent 轨迹（Claude Code、OpenHands、Codex 等）

3. Span 类型（含完整属性架构）

• span-llm - LLM API 调用（模型、令牌、消息、成本）
• span-chain - 多步骤工作流和管道
• span-retriever - 文档检索（文档、分数）
• span-tool - 函数/API 调用（名称、参数）
• span-agent - 多步骤推理 Agent
• span-embedding - 向量生成
• span-reranker - 文档重排序
• span-guardrail - 安全检查
• span-evaluator - LLM 评估
• span-decision - 决策模型调用（路由、分类、评分）——实验性功能

4. 组织方式

• projects-python / projects-typescript - 按应用对跟踪进行分组
• sessions-python / sessions-typescript - 跟踪对话

5. 丰富数据

• metadata-python / metadata-typescript - 自定义属性

6. 生产环境（至关重要）

• production-python / production-typescript - 批处理、PII 脱敏

7. 反馈

• annotations-overview - 反馈概念
• annotations-python / annotations-typescript - 为 Span 添加反馈

参考文件

• fundamentals-overview - Trace、Span 和属性基础知识
• fundamentals-required-attributes - 各 Span 类型的必填字段
• fundamentals-universal-attributes - 常见属性（user.id、session.id）
• fundamentals-flattening - JSON 扁平化规则

常见工作流

• 快速开始：setup-{lang} → instrumentation-auto-{lang} → 检查 Phoenix
• 自定义 Span：setup-{lang} → instrumentation-manual-{lang} → span-{type}
• 会话追踪：使用 sessions-{lang} 了解对话分组模式
• 生产环境：使用 production-{lang} 了解批处理、脱敏和部署

如何使用此技能

导航模式：

# By category prefix
references/setup-*              # Installation and configuration
references/instrumentation-*    # Auto and manual tracing
references/span-*               # Span type specifications
references/sessions-*           # Session tracking
references/production-*         # Production deployment
references/fundamentals-*       # Core concepts

# By language
references/*-python.md          # Python implementations
references/*-typescript.md      # TypeScript implementations

阅读顺序：

1. 从适用于你的语言的 setup-{lang} 开始
2. 选择 instrumentation-auto-{lang} 或 instrumentation-manual-{lang}
3. 根据具体操作需要，参考 span-{type} 文件
4. 查看 fundamentals-* 文件了解属性规范

参考资料

Phoenix 文档：

• Phoenix 文档
• OpenInference 规范

Python API 文档：

• Python OTEL 包 - arize-phoenix-otel API 参考
• Python 客户端包 - arize-phoenix-client API 参考

TypeScript API 文档：

• TypeScript 包 - @arizeai/phoenix-otel、@arizeai/phoenix-client 及其他 TypeScript 包