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