Phoenix Tracing
Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains rule 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
Rule 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 endpointsetup-typescript- Install @arizeai/phoenix-otel, configure endpoint
2. Instrumentation
instrumentation-auto-python- Auto-instrument OpenAI, LangChain, etc.instrumentation-auto-typescript- Auto-instrument supported frameworksinstrumentation-manual-python- Custom spans with decoratorsinstrumentation-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 pipelinesspan-retriever- Document retrieval (documents, scores)span-tool- Function/API calls (name, parameters)span-agent- Multi-step reasoning agentsspan-embedding- Vector generationspan-reranker- Document re-rankingspan-guardrail- Safety checksspan-evaluator- LLM evaluation
4. Organization
projects-python/projects-typescript- Group traces by applicationsessions-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 conceptsannotations-python/annotations-typescript- Add feedback to spans
Reference Files
fundamentals-overview- Traces, spans, attributes basicsfundamentals-required-attributes- Required fields per span typefundamentals-universal-attributes- Common attributes (user.id, session.id)fundamentals-flattening- JSON flattening rulesattributes-messages- Chat message formatattributes-metadata- Custom metadata schemaattributes-graph- Agent workflow attributesattributes-exceptions- Error tracking
Common Attributes
| Attribute | Purpose | Example |
|---|---|---|
openinference.span.kind | Span type (required) | "LLM", "RETRIEVER" |
input.value | Operation input | JSON or text |
output.value | Operation output | JSON or text |
user.id | User identifier | "user_123" |
session.id | Conversation ID | "session_abc" |
llm.model_name | Model identifier | "gpt-4" |
llm.token_count.total | Token usage | 1500 |
tool.name | Tool/function name | "get_weather" |
Common Workflows
Quick Start:
setup-{lang}→ Install and configureinstrumentation-auto-{lang}→ Enable auto-instrumentation- Check Phoenix for traces
Custom Spans:
setup-{lang}→ Installinstrumentation-manual-{lang}→ Add decorators/wrappersspan-{type}→ Reference attributes
Production: production-{lang} → Configure batching and masking
How to Use
Read individual rule files in rules/ for detailed explanations and examples:
rules/setup-python.md
rules/instrumentation-manual-typescript.md
rules/span-llm.md
Use file prefixes to find what you need:
ls rules/span-* # Span type specifications
ls rules/*-python.md # Python guides
ls rules/*-typescript.md # TypeScript guides
References
Phoenix Documentation:
Python API Documentation:
- Python OTEL Package -
arize-phoenix-otelAPI reference - Python Client Package -
arize-phoenix-clientAPI reference
TypeScript API Documentation:
- TypeScript Packages -
@arizeai/phoenix-otel,@arizeai/phoenix-client, and other TypeScript packages