phoenix-tracing

SKILL.md

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