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 observability. Use when implementing LLM tracing, creating custom spans, or deploying to production.4license: Apache-2.05compatibility: Requires Phoenix server. Python skills need arize-phoenix-otel; TypeScript skills need @arizeai/phoenix-otel.6metadata:7 source: https://skillmd.com/skills/github/phoenix-tracing8 author: oss@arize.com9 version: "1.0.0"10 languages: "Python, TypeScript"11---1213# Phoenix Tracing1415Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.1617## When to Apply1819Reference these guidelines when:2021- Setting up Phoenix tracing (Python or TypeScript)22- Creating custom spans for LLM operations23- Adding attributes following OpenInference conventions24- Deploying tracing to production25- Querying and analyzing trace data2627## Reference Categories2829| Priority | Category | Description | Prefix |30| -------- | --------------- | ------------------------------ | -------------------------- |31| 1 | Setup | Installation and configuration | `setup-*` |32| 2 | Instrumentation | Auto and manual tracing | `instrumentation-*` |33| 3 | Span Types | 9 span kinds with attributes | `span-*` |34| 4 | Organization | Projects and sessions | `projects-*`, `sessions-*` |35| 5 | Enrichment | Custom metadata | `metadata-*` |36| 6 | Production | Batch processing, masking | `production-*` |37| 7 | Feedback | Annotations and evaluation | `annotations-*` |3839## Quick Reference4041### 1. Setup (START HERE)4243- [setup-python](references/setup-python.md) - Install arize-phoenix-otel, configure endpoint44- [setup-typescript](references/setup-typescript.md) - Install @arizeai/phoenix-otel, configure endpoint4546### 2. Instrumentation4748- [instrumentation-auto-python](references/instrumentation-auto-python.md) - Auto-instrument OpenAI, LangChain, etc.49- [instrumentation-auto-typescript](references/instrumentation-auto-typescript.md) - Auto-instrument supported frameworks50- [instrumentation-manual-python](references/instrumentation-manual-python.md) - Custom spans with decorators51- [instrumentation-manual-typescript](references/instrumentation-manual-typescript.md) - Custom spans with wrappers5253### 3. Span Types (with full attribute schemas)5455- [span-llm](references/span-llm.md) - LLM API calls (model, tokens, messages, cost)56- [span-chain](references/span-chain.md) - Multi-step workflows and pipelines57- [span-retriever](references/span-retriever.md) - Document retrieval (documents, scores)58- [span-tool](references/span-tool.md) - Function/API calls (name, parameters)59- [span-agent](references/span-agent.md) - Multi-step reasoning agents60- [span-embedding](references/span-embedding.md) - Vector generation61- [span-reranker](references/span-reranker.md) - Document re-ranking62- [span-guardrail](references/span-guardrail.md) - Safety checks63- [span-evaluator](references/span-evaluator.md) - LLM evaluation6465### 4. Organization6667- [projects-python](references/projects-python.md) / [projects-typescript](references/projects-typescript.md) - Group traces by application68- [sessions-python](references/sessions-python.md) / [sessions-typescript](references/sessions-typescript.md) - Track conversations6970### 5. Enrichment7172- [metadata-python](references/metadata-python.md) / [metadata-typescript](references/metadata-typescript.md) - Custom attributes7374### 6. Production (CRITICAL)7576- [production-python](references/production-python.md) / [production-typescript](references/production-typescript.md) - Batch processing, PII masking7778### 7. Feedback7980- [annotations-overview](references/annotations-overview.md) - Feedback concepts81- [annotations-python](references/annotations-python.md) / [annotations-typescript](references/annotations-typescript.md) - Add feedback to spans8283### Reference Files8485- [fundamentals-overview](references/fundamentals-overview.md) - Traces, spans, attributes basics86- [fundamentals-required-attributes](references/fundamentals-required-attributes.md) - Required fields per span type87- [fundamentals-universal-attributes](references/fundamentals-universal-attributes.md) - Common attributes (user.id, session.id)88- [fundamentals-flattening](references/fundamentals-flattening.md) - JSON flattening rules89- [attributes-messages](references/attributes-messages.md) - Chat message format90- [attributes-metadata](references/attributes-metadata.md) - Custom metadata schema91- [attributes-graph](references/attributes-graph.md) - Agent workflow attributes92- [attributes-exceptions](references/attributes-exceptions.md) - Error tracking9394## Common Workflows9596- **Quick Start**: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix97- **Custom Spans**: setup-{lang} → instrumentation-manual-{lang} → span-{type}98- **Session Tracking**: sessions-{lang} for conversation grouping patterns99- **Production**: production-{lang} for batching, masking, and deployment100101## How to Use This Skill102103**Navigation Patterns:**104105```bash106# By category prefix107references/setup-* # Installation and configuration108references/instrumentation-* # Auto and manual tracing109references/span-* # Span type specifications110references/sessions-* # Session tracking111references/production-* # Production deployment112references/fundamentals-* # Core concepts113references/attributes-* # Attribute specifications114115# By language116references/*-python.md # Python implementations117references/*-typescript.md # TypeScript implementations118```119120**Reading Order:**1211. Start with setup-{lang} for your language1222. Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}1233. Reference span-{type} files as needed for specific operations1244. See fundamentals-* files for attribute specifications125126## References127128**Phoenix Documentation:**129130- [Phoenix Documentation](https://docs.arize.com/phoenix)131- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)132133**Python API Documentation:**134135- [Python OTEL Package](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/) - `arize-phoenix-otel` API reference136- [Python Client Package](https://arize-phoenix.readthedocs.io/projects/client/en/latest/) - `arize-phoenix-client` API reference137138**TypeScript API Documentation:**139140- [TypeScript Packages](https://arize-ai.github.io/phoenix/) - `@arizeai/phoenix-otel`, `@arizeai/phoenix-client`, and other TypeScript packages