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 rule 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约定添加属性
将追踪功能部署到生产环境
查询与分析追踪数据

Rule 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 Attributes

通用属性

Attribute	Purpose	Example
`openinference.span.kind`	Span type (required)	`"LLM"` , `"RETRIEVER"`
`input.value`	Operation input	JSON or text
`output.value`	Operation output	JSON or text
`user.id`	User identifier	`"user_123"`
`session.id`	Conversation ID	`"session_abc"`
`llm.model_name`	Model identifier	`"gpt-4"`
`llm.token_count.total`	Token usage	`1500`
`tool.name`	Tool/function name	`"get_weather"`

属性	用途	示例
`openinference.span.kind`	Span类型（必填）	`"LLM"` , `"RETRIEVER"`
`input.value`	操作输入	JSON或文本
`output.value`	操作输出	JSON或文本
`user.id`	用户标识符	`"user_123"`
`session.id`	对话ID	`"session_abc"`
`llm.model_name`	模型标识符	`"gpt-4"`
`llm.token_count.total`	Token用量	`1500`
`tool.name`	工具/函数名称	`"get_weather"`

Common Workflows

常见工作流

Quick Start:

```
setup-{lang}
```
→ Install and configure
```
instrumentation-auto-{lang}
```
→ Enable auto-instrumentation
Check Phoenix for traces

Custom Spans:

```
setup-{lang}
```
→ Install
```
instrumentation-manual-{lang}
```
→ Add decorators/wrappers
```
span-{type}
```
→ Reference attributes

Production:

production-{lang}

→ Configure batching and masking

快速开始：

```
setup-{lang}
```
→ 安装与配置
```
instrumentation-auto-{lang}
```
→ 启用自动埋点
在Phoenix中查看追踪数据

自定义Span：

```
setup-{lang}
```
→ 安装
```
instrumentation-manual-{lang}
```
→ 添加装饰器/包装器
```
span-{type}
```
→ 参考属性规范

生产环境：

production-{lang}

→ 配置批量处理与脱敏

How to Use

使用方法

Read individual rule files in

rules/

for detailed explanations and examples:

rules/setup-python.md
rules/instrumentation-manual-typescript.md
rules/span-llm.md

Use file prefixes to find what you need:

bash

ls rules/span-*           # Span type specifications
ls rules/*-python.md      # Python guides
ls rules/*-typescript.md  # TypeScript guides

阅读

rules/

目录下的单个规则文件获取详细说明与示例：

rules/setup-python.md
rules/instrumentation-manual-typescript.md
rules/span-llm.md

通过文件前缀查找所需内容：

bash

ls rules/span-*           # Span类型规范
ls rules/*-python.md      # Python指南
ls rules/*-typescript.md  # TypeScript指南

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包