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: githubcopilot-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---67# Phoenix Tracing89Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.1011## When to Apply1213Reference these guidelines when:1415- Setting up Phoenix tracing (Python or TypeScript)16- Creating custom spans for LLM operations17- Adding attributes following OpenInference conventions18- Deploying tracing to production19- Querying and analyzing trace data2021## Reference Categories2223| 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-*` |3233## Quick Reference3435### 1. Setup (START HERE)3637- [setup-python](references/setup-python.md) - Install arize-phoenix-otel, configure endpoint38- [setup-typescript](references/setup-typescript.md) - Install @arizeai/phoenix-otel, configure endpoint3940### 2. Instrumentation4142- [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 frameworks44- [instrumentation-manual-python](references/instrumentation-manual-python.md) - Custom spans with decorators45- [instrumentation-manual-typescript](references/instrumentation-manual-typescript.md) - Custom spans with wrappers4647### 3. Span Types (with full attribute schemas)4849- [span-llm](references/span-llm.md) - LLM API calls (model, tokens, messages, cost)50- [span-chain](references/span-chain.md) - Multi-step workflows and pipelines51- [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 agents54- [span-embedding](references/span-embedding.md) - Vector generation55- [span-reranker](references/span-reranker.md) - Document re-ranking56- [span-guardrail](references/span-guardrail.md) - Safety checks57- [span-evaluator](references/span-evaluator.md) - LLM evaluation5859### 4. Organization6061- [projects-python](references/projects-python.md) / [projects-typescript](references/projects-typescript.md) - Group traces by application62- [sessions-python](references/sessions-python.md) / [sessions-typescript](references/sessions-typescript.md) - Track conversations6364### 5. Enrichment6566- [metadata-python](references/metadata-python.md) / [metadata-typescript](references/metadata-typescript.md) - Custom attributes6768### 6. Production (CRITICAL)6970- [production-python](references/production-python.md) / [production-typescript](references/production-typescript.md) - Batch processing, PII masking7172### 7. Feedback7374- [annotations-overview](references/annotations-overview.md) - Feedback concepts75- [annotations-python](references/annotations-python.md) / [annotations-typescript](references/annotations-typescript.md) - Add feedback to spans7677### Reference Files7879- [fundamentals-overview](references/fundamentals-overview.md) - Traces, spans, attributes basics80- [fundamentals-required-attributes](references/fundamentals-required-attributes.md) - Required fields per span type81- [fundamentals-universal-attributes](references/fundamentals-universal-attributes.md) - Common attributes (user.id, session.id)82- [fundamentals-flattening](references/fundamentals-flattening.md) - JSON flattening rules83- [attributes-messages](references/attributes-messages.md) - Chat message format84- [attributes-metadata](references/attributes-metadata.md) - Custom metadata schema85- [attributes-graph](references/attributes-graph.md) - Agent workflow attributes86- [attributes-exceptions](references/attributes-exceptions.md) - Error tracking8788## Common Workflows8990- **Quick Start**: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix91- **Custom Spans**: setup-{lang} → instrumentation-manual-{lang} → span-{type}92- **Session Tracking**: sessions-{lang} for conversation grouping patterns93- **Production**: production-{lang} for batching, masking, and deployment9495## How to Use This Skill9697**Navigation Patterns:**9899```bash100# By category prefix101references/setup-* # Installation and configuration102references/instrumentation-* # Auto and manual tracing103references/span-* # Span type specifications104references/sessions-* # Session tracking105references/production-* # Production deployment106references/fundamentals-* # Core concepts107references/attributes-* # Attribute specifications108109# By language110references/*-python.md # Python implementations111references/*-typescript.md # TypeScript implementations112```113114**Reading Order:**1151. Start with setup-{lang} for your language1162. Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}1173. Reference span-{type} files as needed for specific operations1184. See fundamentals-* files for attribute specifications119120## References121122**Phoenix Documentation:**123124- [Phoenix Documentation](https://docs.arize.com/phoenix)125- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)126127**Python API Documentation:**128129- [Python OTEL Package](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/) - `arize-phoenix-otel` API reference130- [Python Client Package](https://arize-phoenix.readthedocs.io/projects/client/en/latest/) - `arize-phoenix-client` API reference131132**TypeScript API Documentation:**133134- [TypeScript Packages](https://arize-ai.github.io/phoenix/) - `@arizeai/phoenix-otel`, `@arizeai/phoenix-client`, and other TypeScript packages
pyfagorass