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.
- instrumentation-auto-typescript - Auto-instrument supported frameworks
- instrumentation-manual-python - Custom spans with decorators
- instrumentation-manual-typescript - Custom spans with wrappers
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
references/attributes-* # Attribute specifications
# 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.
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
47### 3. Span Types (with full attribute schemas)
48
49- [span-llm](references/span-llm.md) - LLM API calls (model, tokens, messages, cost)
50- [span-chain](references/span-chain.md) - Multi-step workflows and pipelines
51- [span-retriever](references/span-retriever.md) - Document retrieval (documents, scores)
52- [span-tool](references/span-tool.md) - Function/API calls (name, parameters)
53- [span-agent](references/span-agent.md) - Multi-step reasoning agents
54- [span-embedding](references/span-embedding.md) - Vector generation
55- [span-reranker](references/span-reranker.md) - Document re-ranking
56- [span-guardrail](references/span-guardrail.md) - Safety checks
57- [span-evaluator](references/span-evaluator.md) - LLM evaluation
58
59### 4. Organization
60
61- [projects-python](references/projects-python.md) / [projects-typescript](references/projects-typescript.md) - Group traces by application
62- [sessions-python](references/sessions-python.md) / [sessions-typescript](references/sessions-typescript.md) - Track conversations
63
64### 5. Enrichment
65
66- [metadata-python](references/metadata-python.md) / [metadata-typescript](references/metadata-typescript.md) - Custom attributes
67
68### 6. Production (CRITICAL)
69
70- [production-python](references/production-python.md) / [production-typescript](references/production-typescript.md) - Batch processing, PII masking
71
72### 7. Feedback
73
74- [annotations-overview](references/annotations-overview.md) - Feedback concepts
75- [annotations-python](references/annotations-python.md) / [annotations-typescript](references/annotations-typescript.md) - Add feedback to spans
76
77### Reference Files
78
79- [fundamentals-overview](references/fundamentals-overview.md) - Traces, spans, attributes basics
80- [fundamentals-required-attributes](references/fundamentals-required-attributes.md) - Required fields per span type
81- [fundamentals-universal-attributes](references/fundamentals-universal-attributes.md) - Common attributes (user.id, session.id)
82- [fundamentals-flattening](references/fundamentals-flattening.md) - JSON flattening rules
83
84## Common Workflows
85
86- **Quick Start**: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix
87- **Custom Spans**: setup-{lang} → instrumentation-manual-{lang} → span-{type}
88- **Session Tracking**: sessions-{lang} for conversation grouping patterns
89- **Production**: production-{lang} for batching, masking, and deployment
90
91## How to Use This Skill
92
93**Navigation Patterns:**
94
95```bash
96# By category prefix
97references/setup-* # Installation and configuration
98references/instrumentation-* # Auto and manual tracing
99references/span-* # Span type specifications
100references/sessions-* # Session tracking
101references/production-* # Production deployment
102references/fundamentals-* # Core concepts
103references/attributes-* # Attribute specifications
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
gabrielmoreira