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:

• Phoenix Documentation

• OpenInference Spec

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