Phoenix Tracing

# Phoenix Tracing Skill

OpenInference semantic conventions and instrumentation guides for Phoenix.

## Usage

Start with `SKILL.md` for the index and quick reference.

## File Organization

All files in flat `rules/` directory with semantic prefixes:

- `span-*` - Span kinds (LLM, CHAIN, TOOL, etc.)
- `setup-*`, `instrumentation-*` - Getting started guides
- `fundamentals-*`, `attributes-*` - Reference docs
- `annotations-*`, `export-*` - Advanced features

## Reference

- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)
- [Phoenix Documentation](https://docs.arize.com/phoenix)
- [Python OTEL API](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/)
- [Python Client API](https://arize-phoenix.readthedocs.io/projects/client/en/latest/)
- [TypeScript API](https://arize-ai.github.io/phoenix/)


# Annotations Overview

Annotations allow you to add human or automated feedback to traces, spans, documents, and sessions. Annotations are essential for evaluation, quality assessment, and building training datasets.

## Annotation Types

Phoenix supports four types of annotations:

| Type                    | Target                           | Purpose                                  | Example Use Case                 |
| ----------------------- | -------------------------------- | ---------------------------------------- | -------------------------------- |
| **Span Annotation**     | Individual span                  | Feedback on a specific operation         | "This LLM response was accurate" |
| **Document Annotation** | Document within a RETRIEVER span | Feedback on retrieved document relevance | "This document was not helpful"  |
| **Trace Annotation**    | Entire trace                     | Feedback on end-to-end interaction       | "User was satisfied with result" |
| **Session Annotation**  | User session                     | Feedback on multi-turn conversation      | "Session ended successfully"     |

## Annotation Fields

Every annotation has these fields:

### Required Fields

| Field     | Type   | Description                                                                   |
| --------- | ------ | ----------------------------------------------------------------------------- |
| Entity ID | String | ID of the target entity (span_id, trace_id, session_id, or document_position) |
| `name`    | String | Annotation name/label (e.g., "quality", "relevance", "helpfulness")           |

### Result Fields (At Least One Required)

| Field         | Type              | Description                                                       |
| ------------- | ----------------- | ----------------------------------------------------------------- |
| `label`       | String (optional) | Categorical value (e.g., "good", "bad", "relevant", "irrelevant") |
| `score`       | Float (optional)  | Numeric value (typically 0-1, but can be any range)               |
| `explanation` | String (optional) | Free-text explanation of the annotation                           |

**At least one** of `label`, `score`, or `explanation` must be provided.

### Optional Fields

| Field            | Type   | Description                                                                             |
| ---------------- | ------ | --------------------------------------------------------------------------------------- |
| `annotator_kind` | String | Who created this annotation: "HUMAN", "LLM", or "CODE" (default: "HUMAN")               |
| `identifier`     | String | Unique identifier for upsert behavior (updates existing if same name+entity+identifier) |
| `metadata`       | Object | Custom metadata as key-value pairs                                                      |

## Annotator Kinds

| Kind    | Description                    | Example                           |
| ------- | ------------------------------ | --------------------------------- |
| `HUMAN` | Manual feedback from a person  | User ratings, expert labels       |