phoenix-tracing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phoenix Tracing

Phoenix 链路追踪

Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.

这是一份在Phoenix中使用OpenInference链路追踪对LLM应用进行埋点的综合指南，包含覆盖环境搭建、埋点实现、span类型、生产部署的参考文件。

When to Apply

适用场景

Reference these guidelines when:

Setting up Phoenix tracing (Python or TypeScript)
Creating custom spans for LLM operations
Adding attributes following OpenInference conventions
Deploying tracing to production
Querying and analyzing trace data

在以下场景中可参考这些指引：

搭建Phoenix链路追踪（Python或TypeScript）
为LLM操作创建自定义span
遵循OpenInference约定添加属性
将链路追踪部署到生产环境
查询与分析链路数据

Reference Categories

参考类别


setup-*
instrumentation-*
span-*
projects-*
metadata-*
production-*
annotations-*

Priority	Category	Description	Prefix
1	Setup	Installation and configuration	`setup-*`
2	Instrumentation	Auto and manual tracing	`instrumentation-*`
3	Span Types	9 span kinds with attributes	`span-*`
4	Organization	Projects and sessions	`projects-` , `sessions-`
5	Enrichment	Custom metadata	`metadata-*`
6	Production	Batch processing, masking	`production-*`
7	Feedback	Annotations and evaluation	`annotations-*`


setup-*
instrumentation-*
span-*
projects-*
metadata-*
production-*
annotations-*

优先级	分类	描述	前缀
1	环境搭建	安装与配置	`setup-*`
2	埋点实现	自动与手动链路追踪	`instrumentation-*`
3	Span类型	9种带属性的span类别	`span-*`
4	组织管理	项目与会话	`projects-` , `sessions-`
5	信息丰富	自定义元数据	`metadata-*`
6	生产部署	批量处理、数据脱敏	`production-*`
7	反馈优化	标注与评估	`annotations-*`

Quick Reference

快速参考

1. Setup (START HERE)

1. 环境搭建（从这里开始）

setup-python - Install arize-phoenix-otel, configure endpoint
setup-typescript - Install @arizeai/phoenix-otel, configure endpoint

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

2. Instrumentation

2. 埋点实现

instrumentation-auto-python - Auto-instrument OpenAI, LangChain, etc.
instrumentation-auto-typescript - Auto-instrument supported frameworks
instrumentation-manual-python - Custom spans with decorators
instrumentation-manual-typescript - Custom spans with wrappers

instrumentation-auto-python - 自动埋点OpenAI、LangChain等
instrumentation-auto-typescript - 对支持的框架进行自动埋点
instrumentation-manual-python - 通过装饰器创建自定义span
instrumentation-manual-typescript - 通过包装器创建自定义span

3. Span Types (with full attribute schemas)

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

span-llm - LLM API calls (model, tokens, messages, cost)
span-chain - Multi-step workflows and pipelines
span-retriever - Document retrieval (documents, scores)
span-tool - Function/API calls (name, parameters)
span-agent - Multi-step reasoning agents
span-embedding - Vector generation
span-reranker - Document re-ranking
span-guardrail - Safety checks
span-evaluator - LLM evaluation

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. Organization

4. 组织管理

projects-python / projects-typescript - Group traces by application
sessions-python / sessions-typescript - Track conversations

projects-python / projects-typescript - 按应用分组链路
sessions-python / sessions-typescript - 追踪会话

5. Enrichment

5. 信息丰富

metadata-python / metadata-typescript - Custom attributes

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

6. Production (CRITICAL)

6. 生产部署（关键）

production-python / production-typescript - Batch processing, PII masking

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

7. Feedback

7. 反馈优化

annotations-overview - Feedback concepts
annotations-python / annotations-typescript - Add feedback to spans

annotations-overview - 反馈相关概念
annotations-python / annotations-typescript - 为span添加反馈

Reference Files

参考文件

fundamentals-overview - Traces, spans, attributes basics
fundamentals-required-attributes - Required fields per span type
fundamentals-universal-attributes - Common attributes (user.id, session.id)
fundamentals-flattening - JSON flattening rules
attributes-messages - Chat message format
attributes-metadata - Custom metadata schema
attributes-graph - Agent workflow attributes
attributes-exceptions - Error tracking

fundamentals-overview - 链路、span、属性基础
fundamentals-required-attributes - 各span类型必填字段
fundamentals-universal-attributes - 通用属性（user.id、session.id）
fundamentals-flattening - JSON扁平化规则
attributes-messages - 聊天消息格式
attributes-metadata - 自定义元数据Schema
attributes-graph - Agent工作流属性
attributes-exceptions - 错误追踪

Common Workflows

常见工作流

Quick Start: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix
Custom Spans: setup-{lang} → instrumentation-manual-{lang} → span-{type}
Session Tracking: sessions-{lang} for conversation grouping patterns
Production: production-{lang} for batching, masking, and deployment

快速开始: setup-{lang} → instrumentation-auto-{lang} → 检查Phoenix
自定义Span: setup-{lang} → instrumentation-manual-{lang} → span-{type}
会话追踪: 使用sessions-{lang}实现会话分组模式
生产部署: 使用production-{lang}实现批量处理、脱敏与部署

How to Use This Skill

如何使用这份技能指南

Navigation Patterns:

bash

undefined

导航规则:

bash

undefined

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

references/setup-* # 安装与配置 references/instrumentation-* # 自动与手动链路追踪 references/span-* # Span类型规范 references/sessions-* # 会话追踪 references/production-* # 生产部署 references/fundamentals-* # 核心概念 references/attributes-* # 属性规范

By language

按语言

references/-python.md # Python implementations references/-typescript.md # TypeScript implementations


**Reading Order:**
1. Start with setup-{lang} for your language
2. Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}
3. Reference span-{type} files as needed for specific operations
4. See fundamentals-* files for attribute specifications

references/-python.md # Python实现 references/-typescript.md # TypeScript实现


**阅读顺序:**
1. 从对应语言的setup-{lang}开始
2. 选择instrumentation-auto-{lang}或instrumentation-manual-{lang}
3. 按需参考span-{type}文件了解特定操作
4. 查看fundamentals-*文件了解属性规范

References

参考资料

Phoenix Documentation:

Python API Documentation:

Python OTEL Package -
```
arize-phoenix-otel
```
API reference
Python Client Package -
```
arize-phoenix-client
```
API reference

TypeScript API Documentation:

TypeScript Packages -
```
@arizeai/phoenix-otel
```
,
```
@arizeai/phoenix-client
```
, and other TypeScript packages

Phoenix文档:

Python API文档:

Python OTEL Package -
```
arize-phoenix-otel
```
API参考
Python Client Package -
```
arize-phoenix-client
```
API参考

TypeScript API文档:

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