Phoenix Tracing
Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.
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
Reference Categories
| 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-* |
Quick Reference
1. Setup (START HERE)
- setup-python - Install arize-phoenix-otel, configure endpoint
- setup-typescript - Install @arizeai/phoenix-otel, configure endpoint
2. Instrumentation
- instrumentation-auto-python - Auto-instrument OpenAI, LangChain, etc. (also covers OTel GenAI native instrumentation)
- instrumentation-auto-typescript - Auto-instrument supported frameworks
- instrumentation-manual-python - Custom spans with decorators
- instrumentation-manual-typescript - Custom spans with wrappers
- instrumentation-atif-python - Import ATIF agent trajectories (Claude Code, OpenHands, Codex, etc.)
3. Span Types (with full attribute schemas)
- 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
4. Organization
- projects-python / projects-typescript - Group traces by application
- sessions-python / sessions-typescript - Track conversations
5. Enrichment
- metadata-python / metadata-typescript - Custom attributes
6. Production (CRITICAL)
- production-python / production-typescript - Batch processing, PII masking
7. Feedback
- annotations-overview - Feedback concepts
- annotations-python / annotations-typescript - Add feedback to spans
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
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
How to Use This Skill
Navigation Patterns:
# 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
Reading Order:
- Start with setup-{lang} for your language
- Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}
- Reference span-{type} files as needed for specific operations
- See fundamentals-* files for attribute specifications
References
Phoenix Documentation:
Python API Documentation:
TypeScript API Documentation:
- TypeScript Packages -
@arizeai/phoenix-otel, @arizeai/phoenix-client, and other TypeScript packages
1---2name: phoenix-tracing3description: OpenInference semantic conventions and instrumentation for Phoenix AI observability. Use when implementing LLM tracing, creating custom spans, or deploying to production.4license: Apache-2.05---6
7# Phoenix Tracing
8
9Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.
10
11## When to Apply
12
13Reference these guidelines when:
14
15- Setting up Phoenix tracing (Python or TypeScript)
16- Creating custom spans for LLM operations
17- Adding attributes following OpenInference conventions
18- Deploying tracing to production
19- Querying and analyzing trace data
20
21## Reference Categories
22
23| Priority | Category | Description | Prefix |
24| -------- | --------------- | ------------------------------ | -------------------------- |
25| 1 | Setup | Installation and configuration | `setup-*` |
26| 2 | Instrumentation | Auto and manual tracing | `instrumentation-*` |
27| 3 | Span Types | 9 span kinds with attributes | `span-*` |
28| 4 | Organization | Projects and sessions | `projects-*`, `sessions-*` |
29| 5 | Enrichment | Custom metadata | `metadata-*` |
30| 6 | Production | Batch processing, masking | `production-*` |
31| 7 | Feedback | Annotations and evaluation | `annotations-*` |
32
33## Quick Reference
34
35### 1. Setup (START HERE)
36
37- [setup-python](references/setup-python.md) - Install arize-phoenix-otel, configure endpoint
38- [setup-typescript](references/setup-typescript.md) - Install @arizeai/phoenix-otel, configure endpoint
39
40### 2. Instrumentation
41
42- [instrumentation-auto-python](references/instrumentation-auto-python.md) - Auto-instrument OpenAI, LangChain, etc. (also covers OTel GenAI native instrumentation)
43- [instrumentation-auto-typescript](references/instrumentation-auto-typescript.md) - Auto-instrument supported frameworks
44- [instrumentation-manual-python](references/instrumentation-manual-python.md) - Custom spans with decorators
45- [instrumentation-manual-typescript](references/instrumentation-manual-typescript.md) - Custom spans with wrappers
46- [instrumentation-atif-python](references/instrumentation-atif-python.md) - Import ATIF agent trajectories (Claude Code, OpenHands, Codex, etc.)
47
48### 3. Span Types (with full attribute schemas)
49
50- [span-llm](references/span-llm.md) - LLM API calls (model, tokens, messages, cost)
51- [span-chain](references/span-chain.md) - Multi-step workflows and pipelines
52- [span-retriever](references/span-retriever.md) - Document retrieval (documents, scores)
53- [span-tool](references/span-tool.md) - Function/API calls (name, parameters)
54- [span-agent](references/span-agent.md) - Multi-step reasoning agents
55- [span-embedding](references/span-embedding.md) - Vector generation
56- [span-reranker](references/span-reranker.md) - Document re-ranking
57- [span-guardrail](references/span-guardrail.md) - Safety checks
58- [span-evaluator](references/span-evaluator.md) - LLM evaluation
59
60### 4. Organization
61
62- [projects-python](references/projects-python.md) / [projects-typescript](references/projects-typescript.md) - Group traces by application
63- [sessions-python](references/sessions-python.md) / [sessions-typescript](references/sessions-typescript.md) - Track conversations
64
65### 5. Enrichment
66
67- [metadata-python](references/metadata-python.md) / [metadata-typescript](references/metadata-typescript.md) - Custom attributes
68
69### 6. Production (CRITICAL)
70
71- [production-python](references/production-python.md) / [production-typescript](references/production-typescript.md) - Batch processing, PII masking
72
73### 7. Feedback
74
75- [annotations-overview](references/annotations-overview.md) - Feedback concepts
76- [annotations-python](references/annotations-python.md) / [annotations-typescript](references/annotations-typescript.md) - Add feedback to spans
77
78### Reference Files
79
80- [fundamentals-overview](references/fundamentals-overview.md) - Traces, spans, attributes basics
81- [fundamentals-required-attributes](references/fundamentals-required-attributes.md) - Required fields per span type
82- [fundamentals-universal-attributes](references/fundamentals-universal-attributes.md) - Common attributes (user.id, session.id)
83- [fundamentals-flattening](references/fundamentals-flattening.md) - JSON flattening rules
84
85## Common Workflows
86
87- **Quick Start**: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix
88- **Custom Spans**: setup-{lang} → instrumentation-manual-{lang} → span-{type}
89- **Session Tracking**: sessions-{lang} for conversation grouping patterns
90- **Production**: production-{lang} for batching, masking, and deployment
91
92## How to Use This Skill
93
94**Navigation Patterns:**
95
96```bash
97# By category prefix
98references/setup-* # Installation and configuration
99references/instrumentation-* # Auto and manual tracing
100references/span-* # Span type specifications
101references/sessions-* # Session tracking
102references/production-* # Production deployment
103references/fundamentals-* # Core concepts
104
105# By language
106references/*-python.md # Python implementations
107references/*-typescript.md # TypeScript implementations
108```
109
110**Reading Order:**
1111. Start with setup-{lang} for your language
1122. Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}
1133. Reference span-{type} files as needed for specific operations
1144. See fundamentals-* files for attribute specifications
115
116## References
117
118**Phoenix Documentation:**
119
120- [Phoenix Documentation](https://docs.arize.com/phoenix)
121- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)
122
123**Python API Documentation:**
124
125- [Python OTEL Package](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/) - `arize-phoenix-otel` API reference
126- [Python Client Package](https://arize-phoenix.readthedocs.io/projects/client/en/latest/) - `arize-phoenix-client` API reference
127
128**TypeScript API Documentation:**
129
130- [TypeScript Packages](https://arize-ai.github.io/phoenix/) - `@arizeai/phoenix-otel`, `@arizeai/phoenix-client`, and other TypeScript packages
arize-ai