phoenix-tracing

Original：🇺🇸 English

Translated

OpenInference semantic conventions and instrumentation for Phoenix AI observability. Use when implementing LLM tracing, creating custom spans, or deploying to production.

2installs

Sourcearize-ai/phoenix

Added on2026-02-08

NPX Install

npx skill4agent add arize-ai/phoenix phoenix-tracing

SKILL.md Content

View Translation Comparison →

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


setup-*
instrumentation-*
span-*
projects-*
metadata-*
production-*
annotations-*

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 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 configure
```
instrumentation-auto-{lang}
```
→ Enable auto-instrumentation
Check Phoenix for traces

Custom Spans:

```
setup-{lang}
```
→ Install
```
instrumentation-manual-{lang}
```
→ Add decorators/wrappers
```
span-{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:

bash

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-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