Attribution: Sourced from Arize-ai/phoenix by Arize AI.
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
- attributes-messages - Chat message format
- attributes-metadata - Custom metadata schema
- attributes-graph - Agent workflow attributes
- attributes-exceptions - Error tracking
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 observability4license: Apache-2.05---67> **Attribution:** Sourced from [Arize-ai/phoenix](https://github.com/Arize-ai/phoenix) by [Arize AI](https://arize.com).89# Phoenix Tracing1011Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.1213## When to Apply1415Reference these guidelines when:1617- Setting up Phoenix tracing (Python or TypeScript)18- Creating custom spans for LLM operations19- Adding attributes following OpenInference conventions20- Deploying tracing to production21- Querying and analyzing trace data2223## Reference Categories2425| Priority | Category | Description | Prefix |26| -------- | --------------- | ------------------------------ | -------------------------- |27| 1 | Setup | Installation and configuration | `setup-*` |28| 2 | Instrumentation | Auto and manual tracing | `instrumentation-*` |29| 3 | Span Types | 9 span kinds with attributes | `span-*` |30| 4 | Organization | Projects and sessions | `projects-*`, `sessions-*` |31| 5 | Enrichment | Custom metadata | `metadata-*` |32| 6 | Production | Batch processing, masking | `production-*` |33| 7 | Feedback | Annotations and evaluation | `annotations-*` |3435## Quick Reference3637### 1. Setup (START HERE)3839- [setup-python](references/setup-python.md) - Install arize-phoenix-otel, configure endpoint40- [setup-typescript](references/setup-typescript.md) - Install @arizeai/phoenix-otel, configure endpoint4142### 2. Instrumentation4344- [instrumentation-auto-python](references/instrumentation-auto-python.md) - Auto-instrument OpenAI, LangChain, etc.45- [instrumentation-auto-typescript](references/instrumentation-auto-typescript.md) - Auto-instrument supported frameworks46- [instrumentation-manual-python](references/instrumentation-manual-python.md) - Custom spans with decorators47- [instrumentation-manual-typescript](references/instrumentation-manual-typescript.md) - Custom spans with wrappers4849### 3. Span Types (with full attribute schemas)5051- [span-llm](references/span-llm.md) - LLM API calls (model, tokens, messages, cost)52- [span-chain](references/span-chain.md) - Multi-step workflows and pipelines53- [span-retriever](references/span-retriever.md) - Document retrieval (documents, scores)54- [span-tool](references/span-tool.md) - Function/API calls (name, parameters)55- [span-agent](references/span-agent.md) - Multi-step reasoning agents56- [span-embedding](references/span-embedding.md) - Vector generation57- [span-reranker](references/span-reranker.md) - Document re-ranking58- [span-guardrail](references/span-guardrail.md) - Safety checks59- [span-evaluator](references/span-evaluator.md) - LLM evaluation6061### 4. Organization6263- [projects-python](references/projects-python.md) / [projects-typescript](references/projects-typescript.md) - Group traces by application64- [sessions-python](references/sessions-python.md) / [sessions-typescript](references/sessions-typescript.md) - Track conversations6566### 5. Enrichment6768- [metadata-python](references/metadata-python.md) / [metadata-typescript](references/metadata-typescript.md) - Custom attributes6970### 6. Production (CRITICAL)7172- [production-python](references/production-python.md) / [production-typescript](references/production-typescript.md) - Batch processing, PII masking7374### 7. Feedback7576- [annotations-overview](references/annotations-overview.md) - Feedback concepts77- [annotations-python](references/annotations-python.md) / [annotations-typescript](references/annotations-typescript.md) - Add feedback to spans7879### Reference Files8081- [fundamentals-overview](references/fundamentals-overview.md) - Traces, spans, attributes basics82- [fundamentals-required-attributes](references/fundamentals-required-attributes.md) - Required fields per span type83- [fundamentals-universal-attributes](references/fundamentals-universal-attributes.md) - Common attributes (user.id, session.id)84- [fundamentals-flattening](references/fundamentals-flattening.md) - JSON flattening rules85- [attributes-messages](references/attributes-messages.md) - Chat message format86- [attributes-metadata](references/attributes-metadata.md) - Custom metadata schema87- [attributes-graph](references/attributes-graph.md) - Agent workflow attributes88- [attributes-exceptions](references/attributes-exceptions.md) - Error tracking8990## Common Workflows9192- **Quick Start**: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix93- **Custom Spans**: setup-{lang} → instrumentation-manual-{lang} → span-{type}94- **Session Tracking**: sessions-{lang} for conversation grouping patterns95- **Production**: production-{lang} for batching, masking, and deployment9697## How to Use This Skill9899**Navigation Patterns:**100101```bash102# By category prefix103references/setup-* # Installation and configuration104references/instrumentation-* # Auto and manual tracing105references/span-* # Span type specifications106references/sessions-* # Session tracking107references/production-* # Production deployment108references/fundamentals-* # Core concepts109references/attributes-* # Attribute specifications110111# By language112references/*-python.md # Python implementations113references/*-typescript.md # TypeScript implementations114```115116**Reading Order:**1171. Start with setup-{lang} for your language1182. Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}1193. Reference span-{type} files as needed for specific operations1204. See fundamentals-* files for attribute specifications121122## References123124**Phoenix Documentation:**125126- [Phoenix Documentation](https://docs.arize.com/phoenix)127- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)128129**Python API Documentation:**130131- [Python OTEL Package](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/) - `arize-phoenix-otel` API reference132- [Python Client Package](https://arize-phoenix.readthedocs.io/projects/client/en/latest/) - `arize-phoenix-client` API reference133134**TypeScript API Documentation:**135136- [TypeScript Packages](https://arize-ai.github.io/phoenix/) - `@arizeai/phoenix-otel`, `@arizeai/phoenix-client`, and other TypeScript packages
mouadja02