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 等
• instrumentation-auto-typescript - 自动埋点支持的框架
• instrumentation-manual-python - 使用装饰器创建自定义 span
• instrumentation-manual-typescript - 使用包装器创建自定义 span

3. Span 类型（含完整属性模式）

• span-llm - LLM API 调用（模型、token、消息、成本）
• span-chain - 多步骤工作流和流水线
• span-retriever - 文档检索（文档、分数）
• span-tool - 函数/API 调用（名称、参数）
• span-agent - 多步骤推理 Agent
• span-embedding - 向量生成
• span-reranker - 文档重排序
• span-guardrail - 安全检查
• span-evaluator - LLM 评估

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、attribute 基础知识
• fundamentals-required-attributes - 每种 span 类型的必填字段
• fundamentals-universal-attributes - 通用 attribute（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} 了解批处理、掩码和部署

如何使用本 Skill

导航模式：

# 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
references/attributes-*         # Attribute specifications

# 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-* 文件了解 attribute 规范

参考资料

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 包