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

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:

Python OTEL Package - arize-phoenix-otel API reference
Python Client Package - arize-phoenix-client API reference

TypeScript API Documentation:

TypeScript Packages - @arizeai/phoenix-otel, @arizeai/phoenix-client, and other TypeScript packages