phoenix-tracing - Claude MCP Skill

# 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 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:**

```bash
# By category prefix
rules/setup-*              # Installation and configuration
rules/instrumentation-*    # Auto and manual tracing
rules/span-*               # Span type specifications
rules/sessions-*           # Session tracking
rules/production-*         # Production deployment
rules/fundamentals-*       # Core concepts
rules/attributes-*         # Attribute specifications

# By language
rules/*-python.md          # Python implementations
rules/*-typescript.md      # TypeScript implementations
```

**Reading Order:**
1. Start with `setup-{lang}` for your language
2. Choose `instrumentation-auto-{lang}` OR `instrumentation-manual-{lang}`
3. Reference `span-{type}` files as needed for specific operations
4. See `fundamentals-*` files for attribute specifications

## References

**Phoenix Documentation:**

- [Phoenix Documentation](https://docs.arize.com/phoenix)
- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)

**Python API Documentation:**

- [Python OTEL Package](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/) - `arize-phoenix-otel` API reference
- [Python Client Package](https://arize-phoenix.readthedocs.io/projects/client/en/latest/) - `arize-phoenix-client` API reference

**TypeScript API Documentation:**

- [TypeScript Packages](https://arize-ai.github.io/phoenix/) - `@arizeai/phoenix-otel`, `@arizeai/phoenix-client`, and other TypeScript packages