{"kind":"Skill","metadata":{"namespace":"community","name":"phoenix-tracing","version":"0.1.0"},"spec":{"description":"OpenInference semantic conventions and instrumentation for Phoenix AI observability. Use when implementing LLM tracing, creating custom spans, or deploying to production.","files":{"README.md":"# Phoenix Tracing Skill\n\nOpenInference semantic conventions and instrumentation guides for Phoenix.\n\n## Usage\n\nStart with `SKILL.md` for the index and quick reference.\n\n## File Organization\n\nAll files in flat `rules/` directory with semantic prefixes:\n\n- `span-*` - Span kinds (LLM, CHAIN, TOOL, etc.)\n- `setup-*`, `instrumentation-*` - Getting started guides\n- `fundamentals-*`, `attributes-*` - Reference docs\n- `annotations-*`, `export-*` - Advanced features\n\n## Reference\n\n- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)\n- [Phoenix Documentation](https://docs.arize.com/phoenix)\n- [Python OTEL API](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/)\n- [Python Client API](https://arize-phoenix.readthedocs.io/projects/client/en/latest/)\n- [TypeScript API](https://arize-ai.github.io/phoenix/)\n","SKILL.md":"---\nname: phoenix-tracing\ndescription: OpenInference semantic conventions and instrumentation for Phoenix AI observability. Use when implementing LLM tracing, creating custom spans, or deploying to production.\nlicense: Apache-2.0\ncompatibility: Requires Phoenix server. Python skills need arize-phoenix-otel; TypeScript skills need @arizeai/phoenix-otel.\nmetadata:\n  author: oss@arize.com\n  version: \"1.0.0\"\n  languages: \"Python, TypeScript\"\n---\n\n# Phoenix Tracing\n\nComprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.\n\n## When to Apply\n\nReference these guidelines when:\n\n- Setting up Phoenix tracing (Python or TypeScript)\n- Creating custom spans for LLM operations\n- Adding attributes following OpenInference conventions\n- Deploying tracing to production\n- Querying and analyzing trace data\n\n## Reference Categories\n\n| Priority | Category        | Description                    | Prefix                     |\n| -------- | --------------- | ------------------------------ | -------------------------- |\n| 1        | Setup           | Installation and configuration | `setup-*`                  |\n| 2        | Instrumentation | Auto and manual tracing        | `instrumentation-*`        |\n| 3        | Span Types      | 9 span kinds with attributes   | `span-*`                   |\n| 4        | Organization    | Projects and sessions          | `projects-*`, `sessions-*` |\n| 5        | Enrichment      | Custom metadata                | `metadata-*`               |\n| 6        | Production      | Batch processing, masking      | `production-*`             |\n| 7        | Feedback        | Annotations and evaluation     | `annotations-*`            |\n\n## Quick Reference\n\n### 1. Setup (START HERE)\n\n- [setup-python](references/setup-python.md) - Install arize-phoenix-otel, configure endpoint\n- [setup-typescript](references/setup-typescript.md) - Install @arizeai/phoenix-otel, configure endpoint\n\n### 2. Instrumentation\n\n- [instrumentation-auto-python](references/instrumentation-auto-python.md) - Auto-instrument OpenAI, LangChain, etc.\n- [instrumentation-auto-typescript](references/instrumentation-auto-typescript.md) - Auto-instrument supported frameworks\n- [instrumentation-manual-python](references/instrumentation-manual-python.md) - Custom spans with decorators\n- [instrumentation-manual-typescript](references/instrumentation-manual-typescript.md) - Custom spans with wrappers\n\n### 3. Span Types (with full attribute schemas)\n\n- [span-llm](references/span-llm.md) - LLM API calls (model, tokens, messages, cost)\n- [span-chain](references/span-chain.md) - Multi-step workflows and pipelines\n- [span-retriever](references/span-retriever.md) - Document retrieval (documents, scores)\n- [span-tool](references/span-tool.md) - Function/API calls (name, parameters)\n- [span-agent](references/span-agent.md) - Multi-step reasoning agents\n- [span-embedding](references/span-embedding.md) - Vector generation\n- [span-reranker](references/span-reranker.md) - Document re-ranking\n- [span-guardrail](references/span-guardrail.md) - Safety checks\n- [span-evaluator](references/span-evaluator.md) - LLM evaluation\n\n### 4. Organization\n\n- [projects-python](references/projects-python.md) / [projects-typescript](references/projects-typescript.md) - Group traces by application\n- [sessions-python](references/sessions-python.md) / [sessions-typescript](references/sessions-typescript.md) - Track conversations\n\n### 5. Enrichment\n\n- [metadata-python](references/metadata-python.md) / [metadata-typescript](references/metadata-typescript.md) - Custom attributes\n\n### 6. Production (CRITICAL)\n\n- [production-python](references/production-python.md) / [production-typescript](references/production-typescript.md) - Batch processing, PII masking\n\n### 7. Feedback\n\n- [annotations-overview](references/annotations-overview.md) - Feedback concepts\n- [annotations-python](references/annotations-python.md) / [annotations-typescript](references/annotations-typescript.md) - Add feedback to spans\n\n### Reference Files\n\n- [fundamentals-overview](references/fundamentals-overview.md) - Traces, spans, attributes basics\n- [fundamentals-required-attributes](references/fundamentals-required-attributes.md) - Required fields per span type\n- [fundamentals-universal-attributes](references/fundamentals-universal-attributes.md) - Common attributes (user.id, session.id)\n- [fundamentals-flattening](references/fundamentals-flattening.md) - JSON flattening rules\n- [attributes-messages](references/attributes-messages.md) - Chat message format\n- [attributes-metadata](references/attributes-metadata.md) - Custom metadata schema\n- [attributes-graph](references/attributes-graph.md) - Agent workflow attributes\n- [attributes-exceptions](references/attributes-exceptions.md) - Error tracking\n\n## Common Workflows\n\n- **Quick Start**: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix\n- **Custom Spans**: setup-{lang} → instrumentation-manual-{lang} → span-{type}\n- **Session Tracking**: sessions-{lang} for conversation grouping patterns\n- **Production**: production-{lang} for batching, masking, and deployment\n\n## How to Use This Skill\n\n**Navigation Patterns:**\n\n```bash\n# By category prefix\nreferences/setup-*              # Installation and configuration\nreferences/instrumentation-*    # Auto and manual tracing\nreferences/span-*               # Span type specifications\nreferences/sessions-*           # Session tracking\nreferences/production-*         # Production deployment\nreferences/fundamentals-*       # Core concepts\nreferences/attributes-*         # Attribute specifications\n\n# By language\nreferences/*-python.md          # Python implementations\nreferences/*-typescript.md      # TypeScript implementations\n```\n\n**Reading Order:**\n1. Start with setup-{lang} for your language\n2. Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}\n3. Reference span-{type} files as needed for specific operations\n4. See fundamentals-* files for attribute specifications\n\n## References\n\n**Phoenix Documentation:**\n\n- [Phoenix Documentation](https://docs.arize.com/phoenix)\n- [OpenInference Spec](https://github.com/Arize-ai/openinference/tree/main/spec)\n\n**Python API Documentation:**\n\n- [Python OTEL Package](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/) - `arize-phoenix-otel` API reference\n- [Python Client Package](https://arize-phoenix.readthedocs.io/projects/client/en/latest/) - `arize-phoenix-client` API reference\n\n**TypeScript API Documentation:**\n\n- [TypeScript Packages](https://arize-ai.github.io/phoenix/) - `@arizeai/phoenix-otel`, `@arizeai/phoenix-client`, and other TypeScript packages\n","references/annotations-overview.md":"# Annotations Overview\n\nAnnotations 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.\n\n## Annotation Types\n\nPhoenix supports four types of annotations:\n\n| Type                    | Target                           | Purpose                                  | Example Use Case                 |\n| ----------------------- | -------------------------------- | ---------------------------------------- | -------------------------------- |\n| **Span Annotation**     | Individual span                  | Feedback on a specific operation         | \"This LLM response was accurate\" |\n| **Document Annotation** | Document within a RETRIEVER span | Feedback on retrieved document relevance | \"This document was not helpful\"  |\n| **Trace Annotation**    | Entire trace                     | Feedback on end-to-end interaction       | \"User was satisfied with result\" |\n| **Session Annotation**  | User session                     | Feedback on multi-turn conversation      | \"Session ended successfully\"     |\n\n## Annotation Fields\n\nEvery annotation has these fields:\n\n### Required Fields\n\n| Field     | Type   | Description                                                                   |\n| --------- | ------ | ----------------------------------------------------------------------------- |\n| Entity ID | String | ID of the target entity (span_id, trace_id, session_id, or document_position) |\n| `name`    | String | Annotation name/label (e.g., \"quality\", \"relevance\", \"helpfulness\")           |\n\n### Result Fields (At Least One Required)\n\n| Field         | Type              | Description                                                       |\n| ------------- | ----------------- | ----------------------------------------------------------------- |\n| `label`       | String (optional) | Categorical value (e.g., \"good\", \"bad\", \"relevant\", \"irrelevant\") |\n| `score`       | Float (optional)  | Numeric value (typically 0-1, but can be any range)               |\n| `explanation` | String (optional) | Free-text explanation of the annotation                           |\n\n**At least one** of `label`, `score`, or `explanation` must be provided.\n\n### Optional Fields\n\n| Field            | Type   | Description                                                                             |\n| ---------------- | ------ | --------------------------------------------------------------------------------------- |\n| `annotator_kind` | String | Who created this annotation: \"HUMAN\", \"LLM\", or \"CODE\" (default: \"HUMAN\")               |\n| `identifier`     | String | Unique identifier for upsert behavior (updates existing if same name+entity+identifier) |\n| `metadata`       | Object | Custom metadata as key-value pairs                                                      |\n\n## Annotator Kinds\n\n| Kind    | Description                    | Example                           |\n| ------- | ------------------------------ | --------------------------------- |\n| `HUMAN` | Manual feedback from a person  | User ratings, expert labels       |\n| `LLM`   | Automated feedback from an LLM | GPT-4 evaluating response quality |\n| `CODE`  | Automated feedback from code   | Rule-based checks, heuristics     |\n\n## Examples\n\n**Quality Assessment:**\n\n- `quality` - Overall quality (label: good/fair/poor, score: 0-1)\n- `correctness` - Factual accuracy (label: correct/incorrect, score: 0-1)\n- `helpfulness` - User satisfaction (label: helpful/not_helpful, score: 0-1)\n\n**RAG-Specific:**\n\n- `relevance` - Document relevance to query (label: relevant/irrelevant, score: 0-1)\n- `faithfulness` - Answer grounded in context (label: faithful/unfaithful, score: 0-1)\n\n**Safety:**\n\n- `toxicity` - Contains harmful content (score: 0-1)\n- `pii_detected` - Contains personally identifiable information (label: yes/no)\n","references/annotations-python.md":"# Python SDK Annotation Patterns\n\nAdd feedback to spans, traces, documents, and sessions using the Python client.\n\n## Client Setup\n\n```python\nfrom phoenix.client import Client\nclient = Client()  # Default: http://localhost:6006\n```\n\n## Span Annotations\n\nAdd feedback to individual spans:\n\n```python\nclient.spans.add_span_annotation(\n    span_id=\"abc123\",\n    annotation_name=\"quality\",\n    annotator_kind=\"HUMAN\",\n    label=\"high_quality\",\n    score=0.95,\n    explanation=\"Accurate and well-formatted\",\n    metadata={\"reviewer\": \"alice\"},\n    sync=True\n)\n```\n\n## Document Annotations\n\nRate individual documents in RETRIEVER spans:\n\n```python\nclient.spans.add_document_annotation(\n    span_id=\"retriever_span\",\n    document_position=0,  # 0-based index\n    annotation_name=\"relevance\",\n    annotator_kind=\"LLM\",\n    label=\"relevant\",\n    score=0.95\n)\n```\n\n## Trace Annotations\n\nFeedback on entire traces:\n\n```python\nclient.traces.add_trace_annotation(\n    trace_id=\"trace_abc\",\n    annotation_name=\"correctness\",\n    annotator_kind=\"HUMAN\",\n    label=\"correct\",\n    score=1.0\n)\n```\n\n## Span Notes\n\nNotes are a special type of annotation for free-form text — useful for open coding, where reviewers leave qualitative observations on a span before any rubric exists. Later, those notes can be aggregated and distilled into structured labels or scores.\n\nNotes are **append-only**: each call auto-generates a UUIDv4 identifier, so multiple notes naturally accumulate on the same span. Structured annotations are keyed by `(name, span_id, identifier)` — you can have many same-named annotations on one span by supplying distinct identifiers (e.g. one per reviewer); writing the same `(name, span_id, identifier)` overwrites the existing entry.\n\n```python\nclient.spans.add_span_note(\n    span_id=\"abc123def456\",\n    note=\"Unexpected token in response, needs review\",\n)\n```\n\n## Session Annotations\n\nFeedback on multi-turn conversations:\n\n```python\nclient.sessions.add_session_annotation(\n    session_id=\"session_xyz\",\n    annotation_name=\"user_satisfaction\",\n    annotator_kind=\"HUMAN\",\n    label=\"satisfied\",\n    score=0.85\n)\n```\n\n## RAG Pipeline Example\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.client.resources.spans import SpanDocumentAnnotationData\n\nclient = Client()\n\n# Document relevance (batch)\nclient.spans.log_document_annotations(\n    document_annotations=[\n        SpanDocumentAnnotationData(\n            name=\"relevance\", span_id=\"retriever_span\", document_position=i,\n            annotator_kind=\"LLM\", result={\"label\": label, \"score\": score}\n        )\n        for i, (label, score) in enumerate([\n            (\"relevant\", 0.95), (\"relevant\", 0.80), (\"irrelevant\", 0.10)\n        ])\n    ]\n)\n\n# LLM response quality\nclient.spans.add_span_annotation(\n    span_id=\"llm_span\",\n    annotation_name=\"faithfulness\",\n    annotator_kind=\"LLM\",\n    label=\"faithful\",\n    score=0.90\n)\n\n# Overall trace quality\nclient.traces.add_trace_annotation(\n    trace_id=\"trace_123\",\n    annotation_name=\"correctness\",\n    annotator_kind=\"HUMAN\",\n    label=\"correct\",\n    score=1.0\n)\n```\n\n## API Reference\n\n- [Python Client API](https://arize-phoenix.readthedocs.io/projects/client/en/latest/)\n","references/annotations-typescript.md":"# TypeScript SDK Annotation Patterns\n\nAdd feedback to spans, traces, documents, and sessions using the TypeScript client.\n\n## Client Setup\n\n```typescript\nimport { createClient } from \"@arizeai/phoenix-client\";\nconst client = createClient();  // Default: http://localhost:6006\n```\n\n## Span Annotations\n\nAdd feedback to individual spans:\n\n```typescript\nimport { addSpanAnnotation } from \"@arizeai/phoenix-client/spans\";\n\nawait addSpanAnnotation({\n  client,\n  spanAnnotation: {\n    spanId: \"abc123\",\n    name: \"quality\",\n    annotatorKind: \"HUMAN\",\n    label: \"high_quality\",\n    score: 0.95,\n    explanation: \"Accurate and well-formatted\",\n    metadata: { reviewer: \"alice\" }\n  },\n  sync: true\n});\n```\n\n## Span Notes\n\nNotes are a special type of annotation for free-form text — useful for open coding, where reviewers leave qualitative observations on a span before any rubric exists. Later, those notes can be aggregated and distilled into structured labels or scores.\n\nNotes are **append-only**: each call auto-generates a UUIDv4 identifier, so multiple notes naturally accumulate on the same span. Structured annotations are keyed by `(name, spanId, identifier)` — you can have many same-named annotations on one span by supplying distinct identifiers (e.g. one per reviewer); writing the same `(name, spanId, identifier)` overwrites the existing entry.\n\n```typescript\nimport { addSpanNote } from \"@arizeai/phoenix-client/spans\";\n\nawait addSpanNote({\n  client,\n  spanNote: {\n    spanId: \"abc123\",\n    note: \"This span shows unexpected behavior, needs review\"\n  }\n});\n```\n\n## Document Annotations\n\nRate individual documents in RETRIEVER spans:\n\n```typescript\nimport { addDocumentAnnotation } from \"@arizeai/phoenix-client/spans\";\n\nawait addDocumentAnnotation({\n  client,\n  documentAnnotation: {\n    spanId: \"retriever_span\",\n    documentPosition: 0,  // 0-based index\n    name: \"relevance\",\n    annotatorKind: \"LLM\",\n    label: \"relevant\",\n    score: 0.95\n  }\n});\n```\n\n## Trace Annotations\n\nFeedback on entire traces:\n\n```typescript\nimport { addTraceAnnotation } from \"@arizeai/phoenix-client/traces\";\n\nawait addTraceAnnotation({\n  client,\n  traceAnnotation: {\n    traceId: \"trace_abc\",\n    name: \"correctness\",\n    annotatorKind: \"HUMAN\",\n    label: \"correct\",\n    score: 1.0\n  }\n});\n```\n\n## Trace Notes\n\nNotes on entire traces (multiple notes allowed per trace):\n\n```typescript\nimport { addTraceNote } from \"@arizeai/phoenix-client/traces\";\n\nawait addTraceNote({\n  client,\n  traceNote: {\n    traceId: \"abc123def456\",\n    note: \"Needs follow-up — unexpected tool call sequence\"\n  }\n});\n```\n\n## Session Annotations\n\nFeedback on multi-turn conversations:\n\n```typescript\nimport { addSessionAnnotation } from \"@arizeai/phoenix-client/sessions\";\n\nawait addSessionAnnotation({\n  client,\n  sessionAnnotation: {\n    sessionId: \"session_xyz\",\n    name: \"user_satisfaction\",\n    annotatorKind: \"HUMAN\",\n    label: \"satisfied\",\n    score: 0.85\n  }\n});\n```\n\n## RAG Pipeline Example\n\n```typescript\nimport { createClient } from \"@arizeai/phoenix-client\";\nimport { logDocumentAnnotations, addSpanAnnotation } from \"@arizeai/phoenix-client/spans\";\nimport { addTraceAnnotation } from \"@arizeai/phoenix-client/traces\";\n\nconst client = createClient();\n\n// Document relevance (batch)\nawait logDocumentAnnotations({\n  client,\n  documentAnnotations: [\n    { spanId: \"retriever_span\", documentPosition: 0, name: \"relevance\",\n      annotatorKind: \"LLM\", label: \"relevant\", score: 0.95 },\n    { spanId: \"retriever_span\", documentPosition: 1, name: \"relevance\",\n      annotatorKind: \"LLM\", label: \"relevant\", score: 0.80 }\n  ]\n});\n\n// LLM response quality\nawait addSpanAnnotation({\n  client,\n  spanAnnotation: {\n    spanId: \"llm_span\",\n    name: \"faithfulness\",\n    annotatorKind: \"LLM\",\n    label: \"faithful\",\n    score: 0.90\n  }\n});\n\n// Overall trace quality\nawait addTraceAnnotation({\n  client,\n  traceAnnotation: {\n    traceId: \"trace_123\",\n    name: \"correctness\",\n    annotatorKind: \"HUMAN\",\n    label: \"correct\",\n    score: 1.0\n  }\n});\n```\n\n## API Reference\n\n- [TypeScript Client API](https://arize-ai.github.io/phoenix/)\n","references/fundamentals-flattening.md":"# Flattening Convention\n\nOpenInference flattens nested data structures into dot-notation attributes for database compatibility, OpenTelemetry compatibility, and simple querying.\n\n## Flattening Rules\n\n**Objects → Dot Notation**\n\n```javascript\n{ llm: { model_name: \"gpt-4\", token_count: { prompt: 10, completion: 20 } } }\n// becomes\n{ \"llm.model_name\": \"gpt-4\", \"llm.token_count.prompt\": 10, \"llm.token_count.completion\": 20 }\n```\n\n**Arrays → Zero-Indexed Notation**\n\n```javascript\n{ llm: { input_messages: [{ role: \"user\", content: \"Hi\" }] } }\n// becomes\n{ \"llm.input_messages.0.message.role\": \"user\", \"llm.input_messages.0.message.content\": \"Hi\" }\n```\n\n**Message Convention: `.message.` segment required**\n\n```\nllm.input_messages.{index}.message.{field}\nllm.input_messages.0.message.tool_calls.0.tool_call.function.name\n```\n\n## Complete Example\n\n```javascript\n// Original\n{\n  openinference: { span: { kind: \"LLM\" } },\n  llm: {\n    model_name: \"claude-3-5-sonnet-20241022\",\n    invocation_parameters: { temperature: 0.7, max_tokens: 1000 },\n    input_messages: [{ role: \"user\", content: \"Tell me a joke\" }],\n    output_messages: [{ role: \"assistant\", content: \"Why did the chicken cross the road?\" }],\n    token_count: { prompt: 5, completion: 10, total: 15 }\n  }\n}\n\n// Flattened (stored in Phoenix spans.attributes JSONB)\n{\n  \"openinference.span.kind\": \"LLM\",\n  \"llm.model_name\": \"claude-3-5-sonnet-20241022\",\n  \"llm.invocation_parameters\": \"{\\\"temperature\\\": 0.7, \\\"max_tokens\\\": 1000}\",\n  \"llm.input_messages.0.message.role\": \"user\",\n  \"llm.input_messages.0.message.content\": \"Tell me a joke\",\n  \"llm.output_messages.0.message.role\": \"assistant\",\n  \"llm.output_messages.0.message.content\": \"Why did the chicken cross the road?\",\n  \"llm.token_count.prompt\": 5,\n  \"llm.token_count.completion\": 10,\n  \"llm.token_count.total\": 15\n}\n```\n","references/fundamentals-overview.md":"# Overview and Traces \u0026 Spans\n\nThis document covers the fundamental concepts of OpenInference traces and spans in Phoenix.\n\n## Overview\n\nOpenInference is a set of semantic conventions for AI and LLM applications based on OpenTelemetry. Phoenix uses these conventions to capture, store, and analyze traces from AI applications.\n\n**Key Concepts:**\n\n- **Traces** represent end-to-end requests through your application\n- **Spans** represent individual operations within a trace (LLM calls, retrievals, tool invocations)\n- **Attributes** are key-value pairs attached to spans using flattened, dot-notation paths\n- **Span Kinds** categorize the type of operation (LLM, RETRIEVER, TOOL, etc.)\n\n## Traces and Spans\n\n### Trace Hierarchy\n\nA **trace** is a tree of **spans** representing a complete request:\n\n```\nTrace ID: abc123\n├─ Span 1: CHAIN (root span, parent_id = null)\n│  ├─ Span 2: RETRIEVER (parent_id = span_1_id)\n│  │  └─ Span 3: EMBEDDING (parent_id = span_2_id)\n│  └─ Span 4: LLM (parent_id = span_1_id)\n│     └─ Span 5: TOOL (parent_id = span_4_id)\n```\n\n### Context Propagation\n\nSpans maintain parent-child relationships via:\n\n- `trace_id` - Same for all spans in a trace\n- `span_id` - Unique identifier for this span\n- `parent_id` - References parent span's `span_id` (null for root spans)\n\nPhoenix uses these relationships to:\n\n- Build the span tree visualization in the UI\n- Calculate cumulative metrics (tokens, errors) up the tree\n- Enable nested querying (e.g., \"find CHAIN spans containing LLM spans with errors\")\n\n### Span Lifecycle\n\nEach span has:\n\n- `start_time` - When the operation began (Unix timestamp in nanoseconds)\n- `end_time` - When the operation completed\n- `status_code` - OK, ERROR, or UNSET\n- `status_message` - Optional error message\n- `attributes` - object with all semantic convention attributes\n","references/fundamentals-required-attributes.md":"# Required and Recommended Attributes\n\nThis document covers the required attribute and highly recommended attributes for all OpenInference spans.\n\n## Required Attribute\n\n**Every span MUST have exactly one required attribute:**\n\n```json\n{\n  \"openinference.span.kind\": \"LLM\"\n}\n```\n\n## Highly Recommended Attributes\n\nWhile not strictly required, these attributes are **highly recommended** on all spans as they:\n- Enable evaluation and quality assessment\n- Help understand information flow through your application\n- Make traces more useful for debugging\n\n### Input/Output Values\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `input.value` | String | Input to the operation (prompt, query, document) |\n| `output.value` | String | Output from the operation (response, result, answer) |\n\n**Example:**\n```json\n{\n  \"openinference.span.kind\": \"LLM\",\n  \"input.value\": \"What is the capital of France?\",\n  \"output.value\": \"The capital of France is Paris.\"\n}\n```\n\n**Why these matter:**\n- **Evaluations**: Many evaluators (faithfulness, relevance, hallucination detection) require both input and output to assess quality\n- **Information flow**: Seeing inputs/outputs makes it easy to trace how data transforms through your application\n- **Debugging**: When something goes wrong, having the actual input/output makes root cause analysis much faster\n- **Analytics**: Enables pattern analysis across similar inputs or outputs\n\n**Phoenix Behavior:**\n- Input/output displayed prominently in span details\n- Evaluators can automatically access these values\n- Search/filter traces by input or output content\n- Export inputs/outputs for fine-tuning datasets\n\n## Valid Span Kinds\n\nThere are exactly **9 valid span kinds** in OpenInference:\n\n| Span Kind | Purpose | Common Use Case |\n|-----------|---------|-----------------|\n| `LLM` | Language model inference | OpenAI, Anthropic, local LLM calls |\n| `EMBEDDING` | Vector generation | Text-to-vector conversion |\n| `CHAIN` | Application flow orchestration | LangChain chains, custom workflows |\n| `RETRIEVER` | Document/context retrieval | Vector DB queries, semantic search |\n| `RERANKER` | Result reordering | Rerank retrieved documents |\n| `TOOL` | External tool invocation | API calls, function execution |\n| `AGENT` | Autonomous reasoning | ReAct agents, planning loops |\n| `GUARDRAIL` | Safety/policy checks | Content moderation, PII detection |\n| `EVALUATOR` | Quality assessment | Answer relevance, faithfulness scoring |\n","references/fundamentals-universal-attributes.md":"# Universal Attributes\n\nThis document covers attributes that can be used on any span kind in OpenInference.\n\n## Overview\n\nThese attributes can be used on **any span kind** to provide additional context, tracking, and metadata.\n\n## Input/Output\n\n| Attribute          | Type   | Description                                          |\n| ------------------ | ------ | ---------------------------------------------------- |\n| `input.value`      | String | Input to the operation (prompt, query, document)     |\n| `input.mime_type`  | String | MIME type (e.g., \"text/plain\", \"application/json\")   |\n| `output.value`     | String | Output from the operation (response, vector, result) |\n| `output.mime_type` | String | MIME type of output                                  |\n\n### Why Capture I/O?\n\n**Always capture input/output for evaluation-ready spans:**\n- Phoenix evaluators (faithfulness, relevance, Q\u0026A correctness) require `input.value` and `output.value`\n- Phoenix UI displays I/O prominently in trace views for debugging\n- Enables exporting I/O for creating fine-tuning datasets\n- Provides complete context for analyzing agent behavior\n\n**Example attributes:**\n\n```json\n{\n  \"openinference.span.kind\": \"CHAIN\",\n  \"input.value\": \"What is the weather?\",\n  \"input.mime_type\": \"text/plain\",\n  \"output.value\": \"I don't have access to weather data.\",\n  \"output.mime_type\": \"text/plain\"\n}\n```\n\n**See language-specific implementation:**\n- TypeScript: `instrumentation-manual-typescript.md`\n- Python: `instrumentation-manual-python.md`\n\n## Session and User Tracking\n\n| Attribute    | Type   | Description                                    |\n| ------------ | ------ | ---------------------------------------------- |\n| `session.id` | String | Session identifier for grouping related traces |\n| `user.id`    | String | User identifier for per-user analysis          |\n\n**Example:**\n\n```json\n{\n  \"openinference.span.kind\": \"LLM\",\n  \"session.id\": \"session_abc123\",\n  \"user.id\": \"user_xyz789\"\n}\n```\n\n## Metadata\n\n| Attribute  | Type   | Description                                |\n| ---------- | ------ | ------------------------------------------ |\n| `metadata` | string | JSON-serialized object of key-value pairs  |\n\n**Example:**\n\n```json\n{\n  \"openinference.span.kind\": \"LLM\",\n  \"metadata\": \"{\\\"environment\\\": \\\"production\\\", \\\"model_version\\\": \\\"v2.1\\\", \\\"cost_center\\\": \\\"engineering\\\"}\"\n}\n```\n","references/instrumentation-auto-python.md":"# Phoenix Tracing: Auto-Instrumentation (Python)\n\n**Automatically create spans for LLM calls without code changes.**\n\n## Overview\n\nAuto-instrumentation patches supported libraries at runtime to create spans automatically. Use for supported frameworks (LangChain, LlamaIndex, OpenAI SDK, etc.). For custom logic, manual-instrumentation-python.md.\n\n## Supported Frameworks\n\n**Python:**\n\n- LLM SDKs: OpenAI, Anthropic, Bedrock, Mistral, Vertex AI, Groq, Ollama\n- Frameworks: LangChain, LlamaIndex, DSPy, CrewAI, Instructor, Haystack\n- Install: `pip install openinference-instrumentation-{name}`\n\n## Setup\n\n**Install and enable:**\n\n```bash\npip install arize-phoenix-otel\npip install openinference-instrumentation-openai  # Add others as needed\n```\n\n```python\nfrom phoenix.otel import register\n\nregister(project_name=\"my-app\", auto_instrument=True)  # Discovers all installed instrumentors\n```\n\n**Example:**\n\n```python\nfrom phoenix.otel import register\nfrom openai import OpenAI\n\nregister(project_name=\"my-app\", auto_instrument=True)\n\nclient = OpenAI()\nresponse = client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\n```\n\nTraces appear in Phoenix UI with model, input/output, tokens, timing automatically captured. See span kind files for full attribute schemas.\n\n**Selective instrumentation** (explicit control):\n\n```python\nfrom phoenix.otel import register\nfrom openinference.instrumentation.openai import OpenAIInstrumentor\n\ntracer_provider = register(project_name=\"my-app\")  # No auto_instrument\nOpenAIInstrumentor().instrument(tracer_provider=tracer_provider)\n```\n\n## Limitations\n\nAuto-instrumentation does NOT capture:\n\n- Custom business logic\n- Internal function calls\n\n**Example:**\n\n```python\ndef my_custom_workflow(query: str) -\u003e str:\n    preprocessed = preprocess(query)  # Not traced\n    response = client.chat.completions.create(...)  # Traced (auto)\n    postprocessed = postprocess(response)  # Not traced\n    return postprocessed\n```\n\n**Solution:** Add manual instrumentation:\n\n```python\n@tracer.chain\ndef my_custom_workflow(query: str) -\u003e str:\n    preprocessed = preprocess(query)\n    response = client.chat.completions.create(...)\n    postprocessed = postprocess(response)\n    return postprocessed\n```\n","references/instrumentation-auto-typescript.md":"# Auto-Instrumentation (TypeScript)\n\nAutomatically create spans for LLM calls without code changes.\n\n## Supported Frameworks\n\n- **LLM SDKs:** OpenAI\n- **Frameworks:** LangChain\n- **Install:** `npm install @arizeai/openinference-instrumentation-{name}`\n\n## Setup\n\n**CommonJS (automatic):**\n\n```javascript\nconst { register } = require(\"@arizeai/phoenix-otel\");\nconst OpenAI = require(\"openai\");\n\nregister({ projectName: \"my-app\" });\n\nconst client = new OpenAI();\n```\n\n**ESM (manual required):**\n\n```typescript\nimport { register, registerInstrumentations } from \"@arizeai/phoenix-otel\";\nimport { OpenAIInstrumentation } from \"@arizeai/openinference-instrumentation-openai\";\nimport OpenAI from \"openai\";\n\nregister({ projectName: \"my-app\" });\n\nconst instrumentation = new OpenAIInstrumentation();\ninstrumentation.manuallyInstrument(OpenAI);\nregisterInstrumentations({ instrumentations: [instrumentation] });\n```\n\n**Why:** ESM imports are hoisted before `register()` runs.\n\n## Limitations\n\n**What auto-instrumentation does NOT capture:**\n\n```typescript\nasync function myWorkflow(query: string): Promise\u003cstring\u003e {\n  const preprocessed = await preprocess(query);        // Not traced\n  const response = await client.chat.completions.create(...);  // Traced (auto)\n  const postprocessed = await postprocess(response);   // Not traced\n  return postprocessed;\n}\n```\n\n**Solution:** Add manual instrumentation for custom logic:\n\n```typescript\nimport { traceChain } from \"@arizeai/openinference-core\";\n\nconst myWorkflow = traceChain(\n  async (query: string): Promise\u003cstring\u003e =\u003e {\n    const preprocessed = await preprocess(query);\n    const response = await client.chat.completions.create(...);\n    const postprocessed = await postprocess(response);\n    return postprocessed;\n  },\n  { name: \"my-workflow\" }\n);\n```\n\n## Combining Auto + Manual\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\nimport { traceChain } from \"@arizeai/openinference-core\";\n\nregister({ projectName: \"my-app\" });\n\nconst client = new OpenAI();\n\nconst workflow = traceChain(\n  async (query: string) =\u003e {\n    const preprocessed = await preprocess(query);\n    const response = await client.chat.completions.create(...);  // Auto-instrumented\n    return postprocess(response);\n  },\n  { name: \"my-workflow\" }\n);\n```\n","references/instrumentation-manual-python.md":"# Manual Instrumentation (Python)\n\nAdd custom spans using decorators or context managers for fine-grained tracing control.\n\n## Setup\n\n```bash\npip install arize-phoenix-otel\n```\n\n```python\nfrom phoenix.otel import register\ntracer_provider = register(project_name=\"my-app\")\ntracer = tracer_provider.get_tracer(__name__)\n```\n\n## Quick Reference\n\n| Span Kind | Decorator | Use Case |\n|-----------|-----------|----------|\n| CHAIN | `@tracer.chain` | Orchestration, workflows, pipelines |\n| RETRIEVER | `@tracer.retriever` | Vector search, document retrieval |\n| TOOL | `@tracer.tool` | External API calls, function execution |\n| AGENT | `@tracer.agent` | Multi-step reasoning, planning |\n| LLM | `@tracer.llm` | LLM API calls (manual only) |\n| EMBEDDING | `@tracer.embedding` | Embedding generation |\n| RERANKER | `@tracer.reranker` | Document re-ranking |\n| GUARDRAIL | `@tracer.guardrail` | Safety checks, content moderation |\n| EVALUATOR | `@tracer.evaluator` | LLM evaluation, quality checks |\n\n## Decorator Approach (Recommended)\n\n**Use for:** Full function instrumentation, automatic I/O capture\n\n```python\n@tracer.chain\ndef rag_pipeline(query: str) -\u003e str:\n    docs = retrieve_documents(query)\n    ranked = rerank(docs, query)\n    return generate_response(ranked, query)\n\n@tracer.retriever\ndef retrieve_documents(query: str) -\u003e list[dict]:\n    results = vector_db.search(query, top_k=5)\n    return [{\"content\": doc.text, \"score\": doc.score} for doc in results]\n\n@tracer.tool\ndef get_weather(city: str) -\u003e str:\n    response = requests.get(f\"https://api.weather.com/{city}\")\n    return response.json()[\"weather\"]\n```\n\n**Custom span names:**\n\n```python\n@tracer.chain(name=\"rag-pipeline-v2\")\ndef my_workflow(query: str) -\u003e str:\n    return process(query)\n```\n\n## Context Manager Approach\n\n**Use for:** Partial function instrumentation, custom attributes, dynamic control\n\n```python\nfrom opentelemetry.trace import Status, StatusCode\nimport json\n\ndef retrieve_with_metadata(query: str):\n    with tracer.start_as_current_span(\n        \"vector_search\",\n        openinference_span_kind=\"retriever\"\n    ) as span:\n        span.set_attribute(\"input.value\", query)\n\n        results = vector_db.search(query, top_k=5)\n\n        documents = [\n            {\n                \"document.id\": doc.id,\n                \"document.content\": doc.text,\n                \"document.score\": doc.score\n            }\n            for doc in results\n        ]\n        span.set_attribute(\"retrieval.documents\", json.dumps(documents))\n        span.set_status(Status(StatusCode.OK))\n\n        return documents\n```\n\n## Capturing Input/Output\n\n**Always capture I/O for evaluation-ready spans.**\n\n### Automatic I/O Capture (Decorators)\n\nDecorators automatically capture input arguments and return values:\n\n```python  theme={null}\n@tracer.chain\ndef handle_query(user_input: str) -\u003e str:\n    result = agent.generate(user_input)\n    return result.text\n\n# Automatically captures:\n# - input.value: user_input\n# - output.value: result.text\n# - input.mime_type / output.mime_type: auto-detected\n```\n\n### Manual I/O Capture (Context Manager)\n\nUse `set_input()` and `set_output()` for simple I/O capture:\n\n```python  theme={null}\nfrom opentelemetry.trace import Status, StatusCode\n\ndef handle_query(user_input: str) -\u003e str:\n    with tracer.start_as_current_span(\n        \"query.handler\",\n        openinference_span_kind=\"chain\"\n    ) as span:\n        span.set_input(user_input)\n\n        result = agent.generate(user_input)\n\n        span.set_output(result.text)\n        span.set_status(Status(StatusCode.OK))\n\n        return result.text\n```\n\n**What gets captured:**\n\n```json\n{\n  \"input.value\": \"What is 2+2?\",\n  \"input.mime_type\": \"text/plain\",\n  \"output.value\": \"2+2 equals 4.\",\n  \"output.mime_type\": \"text/plain\"\n}\n```\n\n**Why this matters:**\n- Phoenix evaluators require `input.value` and `output.value`\n- Phoenix UI displays I/O prominently for debugging\n- Enables exporting data for fine-tuning datasets\n\n### Custom I/O with Additional Metadata\n\nUse `set_attribute()` for custom attributes alongside I/O:\n\n```python  theme={null}\ndef process_query(query: str):\n    with tracer.start_as_current_span(\n        \"query.process\",\n        openinference_span_kind=\"chain\"\n    ) as span:\n        # Standard I/O\n        span.set_input(query)\n\n        # Custom metadata\n        span.set_attribute(\"input.length\", len(query))\n\n        result = llm.generate(query)\n\n        # Standard output\n        span.set_output(result.text)\n\n        # Custom metadata\n        span.set_attribute(\"output.tokens\", result.usage.total_tokens)\n        span.set_status(Status(StatusCode.OK))\n\n        return result\n```\n\n## See Also\n\n- **Span attributes:** `span-chain.md`, `span-retriever.md`, `span-tool.md`, `span-llm.md`, `span-agent.md`, `span-embedding.md`, `span-reranker.md`, `span-guardrail.md`, `span-evaluator.md`\n- **Auto-instrumentation:** `instrumentation-auto-python.md` for framework integrations\n- **API docs:** https://docs.arize.com/phoenix/tracing/manual-instrumentation\n","references/instrumentation-manual-typescript.md":"# Manual Instrumentation (TypeScript)\n\nAdd custom spans using convenience wrappers or withSpan for fine-grained tracing control.\n\n## Setup\n\n```bash\nnpm install @arizeai/phoenix-otel @arizeai/openinference-core\n```\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\nregister({ projectName: \"my-app\" });\n```\n\n## Quick Reference\n\n| Span Kind | Method | Use Case |\n|-----------|--------|----------|\n| CHAIN | `traceChain` | Workflows, pipelines, orchestration |\n| AGENT | `traceAgent` | Multi-step reasoning, planning |\n| TOOL | `traceTool` | External APIs, function calls |\n| RETRIEVER | `withSpan` | Vector search, document retrieval |\n| LLM | `withSpan` | LLM API calls (prefer auto-instrumentation) |\n| EMBEDDING | `withSpan` | Embedding generation |\n| RERANKER | `withSpan` | Document re-ranking |\n| GUARDRAIL | `withSpan` | Safety checks, content moderation |\n| EVALUATOR | `withSpan` | LLM evaluation |\n\n## Convenience Wrappers\n\n```typescript\nimport { traceChain, traceAgent, traceTool } from \"@arizeai/openinference-core\";\n\n// CHAIN - workflows\nconst pipeline = traceChain(\n  async (query: string) =\u003e {\n    const docs = await retrieve(query);\n    return await generate(docs, query);\n  },\n  { name: \"rag-pipeline\" }\n);\n\n// AGENT - reasoning\nconst agent = traceAgent(\n  async (question: string) =\u003e {\n    const thought = await llm.generate(`Think: ${question}`);\n    return await processThought(thought);\n  },\n  { name: \"my-agent\" }\n);\n\n// TOOL - function calls\nconst getWeather = traceTool(\n  async (city: string) =\u003e fetch(`/api/weather/${city}`).then(r =\u003e r.json()),\n  { name: \"get-weather\" }\n);\n```\n\n## withSpan for Other Kinds\n\n```typescript\nimport { withSpan, getInputAttributes, getRetrieverAttributes } from \"@arizeai/openinference-core\";\n\n// RETRIEVER with custom attributes\nconst retrieve = withSpan(\n  async (query: string) =\u003e {\n    const results = await vectorDb.search(query, { topK: 5 });\n    return results.map(doc =\u003e ({ content: doc.text, score: doc.score }));\n  },\n  {\n    kind: \"RETRIEVER\",\n    name: \"vector-search\",\n    processInput: (query) =\u003e getInputAttributes(query),\n    processOutput: (docs) =\u003e getRetrieverAttributes({ documents: docs })\n  }\n);\n```\n\n**Options:**\n\n```typescript\nwithSpan(fn, {\n  kind: \"RETRIEVER\",              // OpenInference span kind\n  name: \"span-name\",              // Span name (defaults to function name)\n  processInput: (args) =\u003e {},     // Transform input to attributes\n  processOutput: (result) =\u003e {},  // Transform output to attributes\n  attributes: { key: \"value\" }    // Static attributes\n});\n```\n\n## Capturing Input/Output\n\n**Always capture I/O for evaluation-ready spans.** Use `getInputAttributes` and `getOutputAttributes` helpers for automatic MIME type detection:\n\n```typescript\nimport {\n  getInputAttributes,\n  getOutputAttributes,\n  withSpan,\n} from \"@arizeai/openinference-core\";\n\nconst handleQuery = withSpan(\n  async (userInput: string) =\u003e {\n    const result = await agent.generate({ prompt: userInput });\n    return result;\n  },\n  {\n    name: \"query.handler\",\n    kind: \"CHAIN\",\n    // Use helpers - automatic MIME type detection\n    processInput: (input) =\u003e getInputAttributes(input),\n    processOutput: (result) =\u003e getOutputAttributes(result.text),\n  }\n);\n\nawait handleQuery(\"What is 2+2?\");\n```\n\n**What gets captured:**\n\n```json\n{\n  \"input.value\": \"What is 2+2?\",\n  \"input.mime_type\": \"text/plain\",\n  \"output.value\": \"2+2 equals 4.\",\n  \"output.mime_type\": \"text/plain\"\n}\n```\n\n**Helper behavior:**\n- Strings → `text/plain`\n- Objects/Arrays → `application/json` (automatically serialized)\n- `undefined`/`null` → No attributes set\n\n**Why this matters:**\n- Phoenix evaluators require `input.value` and `output.value`\n- Phoenix UI displays I/O prominently for debugging\n- Enables exporting data for fine-tuning datasets\n\n### Custom I/O Processing\n\nAdd custom metadata alongside standard I/O attributes:\n\n```typescript\nconst processWithMetadata = withSpan(\n  async (query: string) =\u003e {\n    const result = await llm.generate(query);\n    return result;\n  },\n  {\n    name: \"query.process\",\n    kind: \"CHAIN\",\n    processInput: (query) =\u003e ({\n      \"input.value\": query,\n      \"input.mime_type\": \"text/plain\",\n      \"input.length\": query.length,  // Custom attribute\n    }),\n    processOutput: (result) =\u003e ({\n      \"output.value\": result.text,\n      \"output.mime_type\": \"text/plain\",\n      \"output.tokens\": result.usage?.totalTokens,  // Custom attribute\n    }),\n  }\n);\n```\n\n## See Also\n\n- **Span attributes:** `span-chain.md`, `span-retriever.md`, `span-tool.md`, etc.\n- **Attribute helpers:** https://docs.arize.com/phoenix/tracing/manual-instrumentation-typescript#attribute-helpers\n- **Auto-instrumentation:** `instrumentation-auto-typescript.md` for framework integrations\n","references/metadata-python.md":"# Phoenix Tracing: Custom Metadata (Python)\n\nAdd custom attributes to spans for richer observability.\n\n## Install\n\n```bash\npip install arize-phoenix-otel  # context managers and SpanAttributes re-exported since 0.16.0\n```\n\n## Session\n\n```python\nfrom phoenix.otel import using_session\n\nwith using_session(session_id=\"my-session-id\"):\n    # Spans get: \"session.id\" = \"my-session-id\"\n    ...\n```\n\n## User\n\n```python\nfrom phoenix.otel import using_user\n\nwith using_user(\"my-user-id\"):\n    # Spans get: \"user.id\" = \"my-user-id\"\n    ...\n```\n\n## Metadata\n\n```python\nfrom phoenix.otel import using_metadata\n\nwith using_metadata({\"key\": \"value\", \"experiment_id\": \"exp_123\"}):\n    # Spans get: \"metadata\" = '{\"key\": \"value\", \"experiment_id\": \"exp_123\"}'\n    ...\n```\n\n## Tags\n\n```python\nfrom phoenix.otel import using_tags\n\nwith using_tags([\"tag_1\", \"tag_2\"]):\n    # Spans get: \"tag.tags\" = '[\"tag_1\", \"tag_2\"]'\n    ...\n```\n\n## Combined (using_attributes)\n\n```python\nfrom phoenix.otel import using_attributes\n\nwith using_attributes(\n    session_id=\"my-session-id\",\n    user_id=\"my-user-id\",\n    metadata={\"environment\": \"production\"},\n    tags=[\"prod\", \"v2\"],\n    prompt_template=\"Answer: {question}\",\n    prompt_template_version=\"v1.0\",\n    prompt_template_variables={\"question\": \"What is Phoenix?\"},\n):\n    # All attributes applied to spans in this context\n    ...\n```\n\n## On a Single Span\n\n```python\nspan.set_attribute(\"metadata\", json.dumps({\"key\": \"value\"}))\nspan.set_attribute(\"user.id\", \"user_123\")\nspan.set_attribute(\"session.id\", \"session_456\")\n```\n\n## As Decorators\n\nAll context managers can be used as decorators:\n\n```python\nfrom phoenix.otel import using_session, using_user, using_metadata\n\n@using_session(session_id=\"my-session-id\")\n@using_user(\"my-user-id\")\n@using_metadata({\"env\": \"prod\"})\ndef my_function():\n    ...\n```\n","references/metadata-typescript.md":"# Phoenix Tracing: Custom Metadata (TypeScript)\n\nAdd custom attributes to spans for richer observability.\n\n## Using Context (Propagates to All Child Spans)\n\n```typescript\nimport { context } from \"@arizeai/phoenix-otel\";\nimport { setMetadata } from \"@arizeai/openinference-core\";\n\ncontext.with(\n  setMetadata(context.active(), {\n    experiment_id: \"exp_123\",\n    model_version: \"gpt-4-1106-preview\",\n    environment: \"production\",\n  }),\n  async () =\u003e {\n    // All spans created within this block will have:\n    // \"metadata\" = '{\"experiment_id\": \"exp_123\", ...}'\n    await myApp.run(query);\n  }\n);\n```\n\n## On a Single Span\n\n```typescript\nimport { traceChain } from \"@arizeai/openinference-core\";\nimport { trace } from \"@arizeai/phoenix-otel\";\n\nconst myFunction = traceChain(\n  async (input: string) =\u003e {\n    const span = trace.getActiveSpan();\n\n    span?.setAttribute(\n      \"metadata\",\n      JSON.stringify({\n        experiment_id: \"exp_123\",\n        model_version: \"gpt-4-1106-preview\",\n        environment: \"production\",\n      })\n    );\n\n    return result;\n  },\n  { name: \"my-function\" }\n);\n\nawait myFunction(\"hello\");\n```\n","references/production-python.md":"# Phoenix Tracing: Production Guide (Python)\n\n**CRITICAL: Configure batching, data masking, and span filtering for production deployment.**\n\n## Metadata\n\n| Attribute | Value |\n|-----------|-------|\n| Priority | Critical - production readiness |\n| Impact | Security, Performance |\n| Setup Time | 5-15 min |\n\n## Batch Processing\n\n**Enable batch processing for production efficiency.** Batching reduces network overhead by sending spans in groups rather than individually.\n\n## Data Masking (PII Protection)\n\n**Environment variables:**\n\n```bash\nexport OPENINFERENCE_HIDE_INPUTS=true          # Hide input.value\nexport OPENINFERENCE_HIDE_OUTPUTS=true         # Hide output.value\nexport OPENINFERENCE_HIDE_INPUT_MESSAGES=true  # Hide LLM input messages\nexport OPENINFERENCE_HIDE_OUTPUT_MESSAGES=true # Hide LLM output messages\nexport OPENINFERENCE_HIDE_INPUT_IMAGES=true    # Hide image content\nexport OPENINFERENCE_HIDE_INPUT_TEXT=true      # Hide embedding text\nexport OPENINFERENCE_BASE64_IMAGE_MAX_LENGTH=10000  # Limit image size\n```\n\n**Python TraceConfig:**\n\n```python\nfrom phoenix.otel import register\nfrom openinference.instrumentation import TraceConfig\n\nconfig = TraceConfig(\n    hide_inputs=True,\n    hide_outputs=True,\n    hide_input_messages=True\n)\nregister(trace_config=config)\n```\n\n**Precedence:** Code \u003e Environment variables \u003e Defaults\n\n---\n\n## Span Filtering\n\n**Suppress specific code blocks:**\n\n```python\nfrom phoenix.otel import suppress_tracing\n\nwith suppress_tracing():\n    internal_logging()  # No spans generated\n```\n","references/production-typescript.md":"# Phoenix Tracing: Production Guide (TypeScript)\n\n**CRITICAL: Configure batching, data masking, and span filtering for production deployment.**\n\n## Metadata\n\n| Attribute | Value |\n|-----------|-------|\n| Priority | Critical - production readiness |\n| Impact | Security, Performance |\n| Setup Time | 5-15 min |\n\n## Batch Processing\n\n**Enable batch processing for production efficiency.** Batching reduces network overhead by sending spans in groups rather than individually.\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nconst provider = register({\n  projectName: \"my-app\",\n  batch: true,  // Production default\n});\n```\n\n### Shutdown Handling\n\n**CRITICAL:** Spans may not be exported if still queued in the processor when your process exits. Call `provider.shutdown()` to explicitly flush before exit.\n\n```typescript\n// Explicit shutdown to flush queued spans\nconst provider = register({\n  projectName: \"my-app\",\n  batch: true,\n});\n\nasync function main() {\n  await doWork();\n  await provider.shutdown();  // Flush spans before exit\n}\n\nmain().catch(async (error) =\u003e {\n  console.error(error);\n  await provider.shutdown();  // Flush on error too\n  process.exit(1);\n});\n```\n\n**Graceful termination signals:**\n\n```typescript\n// Graceful shutdown on SIGTERM\nconst provider = register({\n  projectName: \"my-server\",\n  batch: true,\n});\n\nprocess.on(\"SIGTERM\", async () =\u003e {\n  await provider.shutdown();\n  process.exit(0);\n});\n```\n\n---\n\n## Data Masking (PII Protection)\n\n**Environment variables:**\n\n```bash\nexport OPENINFERENCE_HIDE_INPUTS=true          # Hide input.value\nexport OPENINFERENCE_HIDE_OUTPUTS=true         # Hide output.value\nexport OPENINFERENCE_HIDE_INPUT_MESSAGES=true  # Hide LLM input messages\nexport OPENINFERENCE_HIDE_OUTPUT_MESSAGES=true # Hide LLM output messages\nexport OPENINFERENCE_HIDE_INPUT_IMAGES=true    # Hide image content\nexport OPENINFERENCE_HIDE_INPUT_TEXT=true      # Hide embedding text\nexport OPENINFERENCE_BASE64_IMAGE_MAX_LENGTH=10000  # Limit image size\n```\n\n**TypeScript TraceConfig:**\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\nimport { OpenAIInstrumentation } from \"@arizeai/openinference-instrumentation-openai\";\n\nconst traceConfig = {\n  hideInputs: true,\n  hideOutputs: true,\n  hideInputMessages: true\n};\n\nconst instrumentation = new OpenAIInstrumentation({ traceConfig });\n```\n\n**Precedence:** Code \u003e Environment variables \u003e Defaults\n\n---\n\n## Span Filtering\n\n**Suppress specific code blocks:**\n\n```typescript\nimport { suppressTracing } from \"@opentelemetry/core\";\nimport { context } from \"@opentelemetry/api\";\n\nawait context.with(suppressTracing(context.active()), async () =\u003e {\n  internalLogging(); // No spans generated\n});\n```\n\n**Sampling:**\n\n```bash\nexport OTEL_TRACES_SAMPLER=\"parentbased_traceidratio\"\nexport OTEL_TRACES_SAMPLER_ARG=\"0.1\"  # Sample 10%\n```\n\n---\n\n## Error Handling\n\n```typescript\nimport { SpanStatusCode } from \"@opentelemetry/api\";\n\ntry {\n  result = await riskyOperation();\n  span?.setStatus({ code: SpanStatusCode.OK });\n} catch (e) {\n  span?.recordException(e);\n  span?.setStatus({ code: SpanStatusCode.ERROR });\n  throw e;\n}\n```\n\n---\n\n## Production Checklist\n\n- [ ] Batch processing enabled\n- [ ] **Shutdown handling:** Call `provider.shutdown()` before exit to flush queued spans\n- [ ] **Graceful termination:** Flush spans on SIGTERM/SIGINT signals\n- [ ] Data masking configured (`HIDE_INPUTS`/`HIDE_OUTPUTS` if PII)\n- [ ] Span filtering for health checks/noisy paths\n- [ ] Error handling implemented\n- [ ] Graceful degradation if Phoenix unavailable\n- [ ] Performance tested\n- [ ] Monitoring configured (Phoenix UI checked)\n","references/projects-python.md":"# Phoenix Tracing: Projects (Python)\n\n**Organize traces by application using projects (Phoenix's top-level grouping).**\n\n## Overview\n\nProjects group traces for a single application or experiment.\n\n**Use for:** Environments (dev/staging/prod), A/B testing, versioning\n\n## Setup\n\n### Environment Variable (Recommended)\n\n```bash\nexport PHOENIX_PROJECT_NAME=\"my-app-prod\"\n```\n\n```python\nimport os\nos.environ[\"PHOENIX_PROJECT_NAME\"] = \"my-app-prod\"\nfrom phoenix.otel import register\nregister()  # Uses \"my-app-prod\"\n```\n\n### Code\n\n```python\nfrom phoenix.otel import register\nregister(project_name=\"my-app-prod\")\n```\n\n## Use Cases\n\n**Environments:**\n\n```python\n# Dev, staging, prod\nregister(project_name=\"my-app-dev\")\nregister(project_name=\"my-app-staging\")\nregister(project_name=\"my-app-prod\")\n```\n\n**A/B Testing:**\n\n```python\n# Compare models\nregister(project_name=\"chatbot-gpt4\")\nregister(project_name=\"chatbot-claude\")\n```\n\n**Versioning:**\n\n```python\n# Track versions\nregister(project_name=\"my-app-v1\")\nregister(project_name=\"my-app-v2\")\n```\n\n## Switching Projects (Python Notebooks Only)\n\n```python\nfrom openinference.instrumentation import dangerously_using_project\nfrom phoenix.otel import register\n\nregister(project_name=\"my-app\")\n\n# Switch temporarily for evals\nwith dangerously_using_project(\"my-eval-project\"):\n    run_evaluations()\n```\n\n**⚠️ Only use in notebooks/scripts, not production.**\n","references/projects-typescript.md":"# Phoenix Tracing: Projects (TypeScript)\n\n**Organize traces by application using projects (Phoenix's top-level grouping).**\n\n## Overview\n\nProjects group traces for a single application or experiment.\n\n**Use for:** Environments (dev/staging/prod), A/B testing, versioning\n\n## Setup\n\n### Environment Variable (Recommended)\n\n```bash\nexport PHOENIX_PROJECT_NAME=\"my-app-prod\"\n```\n\n```typescript\nprocess.env.PHOENIX_PROJECT_NAME = \"my-app-prod\";\nimport { register } from \"@arizeai/phoenix-otel\";\nregister();  // Uses \"my-app-prod\"\n```\n\n### Code\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\nregister({ projectName: \"my-app-prod\" });\n```\n\n## Use Cases\n\n**Environments:**\n```typescript\n// Dev, staging, prod\nregister({ projectName: \"my-app-dev\" });\nregister({ projectName: \"my-app-staging\" });\nregister({ projectName: \"my-app-prod\" });\n```\n\n**A/B Testing:**\n```typescript\n// Compare models\nregister({ projectName: \"chatbot-gpt4\" });\nregister({ projectName: \"chatbot-claude\" });\n```\n\n**Versioning:**\n```typescript\n// Track versions\nregister({ projectName: \"my-app-v1\" });\nregister({ projectName: \"my-app-v2\" });\n```\n","references/sessions-python.md":"# Sessions (Python)\n\nTrack multi-turn conversations by grouping traces with session IDs.\n\n## Setup\n\n```python\nfrom phoenix.otel import using_session\n\nwith using_session(session_id=\"user_123_conv_456\"):\n    response = llm.invoke(prompt)\n```\n\n## Best Practices\n\n**Bad: Only parent span gets session ID**\n\n```python\nfrom phoenix.otel import SpanAttributes\nfrom opentelemetry import trace\n\nspan = trace.get_current_span()\nspan.set_attribute(SpanAttributes.SESSION_ID, session_id)\nresponse = client.chat.completions.create(...)\n```\n\n**Good: All child spans inherit session ID**\n\n```python\nwith using_session(session_id):\n    response = client.chat.completions.create(...)\n    result = my_custom_function()\n```\n\n**Why:** `using_session()` propagates session ID to all nested spans automatically.\n\n## Session ID Patterns\n\n```python\nimport uuid\n\nsession_id = str(uuid.uuid4())\nsession_id = f\"user_{user_id}_conv_{conversation_id}\"\nsession_id = f\"debug_{timestamp}\"\n```\n\nGood: `str(uuid.uuid4())`, `\"user_123_conv_456\"`\nBad: `\"session_1\"`, `\"test\"`, empty string\n\n## Multi-Turn Chatbot Example\n\n```python\nimport uuid\nfrom phoenix.otel import using_session\n\nsession_id = str(uuid.uuid4())\nmessages = []\n\ndef send_message(user_input: str) -\u003e str:\n    messages.append({\"role\": \"user\", \"content\": user_input})\n\n    with using_session(session_id):\n        response = client.chat.completions.create(\n            model=\"gpt-4\",\n            messages=messages\n        )\n\n    assistant_message = response.choices[0].message.content\n    messages.append({\"role\": \"assistant\", \"content\": assistant_message})\n    return assistant_message\n```\n\n## Additional Attributes\n\n```python\nfrom phoenix.otel import using_attributes\n\nwith using_attributes(\n    user_id=\"user_123\",\n    session_id=\"conv_456\",\n    metadata={\"tier\": \"premium\", \"region\": \"us-west\"}\n):\n    response = llm.invoke(prompt)\n```\n\n## LangChain Integration\n\nLangChain threads are automatically recognized as sessions:\n\n```python\nfrom langchain.chat_models import ChatOpenAI\n\nresponse = llm.invoke(\n    [HumanMessage(content=\"Hi!\")],\n    config={\"metadata\": {\"thread_id\": \"user_123_thread\"}}\n)\n```\n\nPhoenix recognizes: `thread_id`, `session_id`, `conversation_id`\n\n## See Also\n\n- **TypeScript sessions:** `sessions-typescript.md`\n- **Session docs:** https://docs.arize.com/phoenix/tracing/sessions\n","references/sessions-typescript.md":"# Sessions (TypeScript)\n\nTrack multi-turn conversations by grouping traces with session IDs. **Use `withSpan` directly from `@arizeai/openinference-core`** - no wrappers or custom utilities needed.\n\n## Core Concept\n\n**Session Pattern:**\n1. Generate a unique `session.id` once at application startup\n2. Export SESSION_ID, import `withSpan` where needed\n3. Use `withSpan` to create a parent CHAIN span with `session.id` for each interaction\n4. All child spans (LLM, TOOL, AGENT, etc.) automatically group under the parent\n5. Query traces by `session.id` in Phoenix to see all interactions\n\n## Implementation (Best Practice)\n\n### 1. Setup (instrumentation.ts)\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\nimport { randomUUID } from \"node:crypto\";\n\n// Initialize Phoenix\nregister({\n  projectName: \"your-app\",\n  url: process.env.PHOENIX_COLLECTOR_ENDPOINT || \"http://localhost:6006\",\n  apiKey: process.env.PHOENIX_API_KEY,\n  batch: true,\n});\n\n// Generate and export session ID\nexport const SESSION_ID = randomUUID();\n```\n\n### 2. Usage (app code)\n\n```typescript\nimport { withSpan } from \"@arizeai/openinference-core\";\nimport { SESSION_ID } from \"./instrumentation\";\n\n// Use withSpan directly - no wrapper needed\nconst handleInteraction = withSpan(\n  async () =\u003e {\n    const result = await agent.generate({ prompt: userInput });\n    return result;\n  },\n  {\n    name: \"cli.interaction\",\n    kind: \"CHAIN\",\n    attributes: { \"session.id\": SESSION_ID },\n  }\n);\n\n// Call it\nconst result = await handleInteraction();\n```\n\n### With Input Parameters\n\n```typescript\nconst processQuery = withSpan(\n  async (query: string) =\u003e {\n    return await agent.generate({ prompt: query });\n  },\n  {\n    name: \"process.query\",\n    kind: \"CHAIN\",\n    attributes: { \"session.id\": SESSION_ID },\n  }\n);\n\nawait processQuery(\"What is 2+2?\");\n```\n\n## Key Points\n\n### Session ID Scope\n- **CLI/Desktop Apps**: Generate once at process startup\n- **Web Servers**: Generate per-user session (e.g., on login, store in session storage)\n- **Stateless APIs**: Accept session.id as a parameter from client\n\n### Span Hierarchy\n```\ncli.interaction (CHAIN) ← session.id here\n├── ai.generateText (AGENT)\n│   ├── ai.generateText.doGenerate (LLM)\n│   └── ai.toolCall (TOOL)\n└── ai.generateText.doGenerate (LLM)\n```\n\nThe `session.id` is only set on the **root span**. Child spans are automatically grouped by the trace hierarchy.\n\n### Querying Sessions\n\n```bash\n# Get all traces for a session\nnpx @arizeai/phoenix-cli traces \\\n  --endpoint http://localhost:6006 \\\n  --project your-app \\\n  --format raw \\\n  --no-progress | \\\n  jq '.[] | select(.spans[0].attributes[\"session.id\"] == \"YOUR-SESSION-ID\")'\n```\n\n## Dependencies\n\n```json\n{\n  \"dependencies\": {\n    \"@arizeai/openinference-core\": \"^2.0.5\",\n    \"@arizeai/phoenix-otel\": \"^0.4.1\"\n  }\n}\n```\n\n**Note:** `@opentelemetry/api` is NOT needed - it's only for manual span management.\n\n## Why This Pattern?\n\n1. **Simple**: Just export SESSION_ID, use withSpan directly - no wrappers\n2. **Built-in**: `withSpan` from `@arizeai/openinference-core` handles everything\n3. **Type-safe**: Preserves function signatures and type information\n4. **Automatic lifecycle**: Handles span creation, error tracking, and cleanup\n5. **Framework-agnostic**: Works with any LLM framework (AI SDK, LangChain, etc.)\n6. **No extra deps**: Don't need `@opentelemetry/api` or custom utilities\n\n## Adding More Attributes\n\n```typescript\nimport { withSpan } from \"@arizeai/openinference-core\";\nimport { SESSION_ID } from \"./instrumentation\";\n\nconst handleWithContext = withSpan(\n  async (userInput: string) =\u003e {\n    return await agent.generate({ prompt: userInput });\n  },\n  {\n    name: \"cli.interaction\",\n    kind: \"CHAIN\",\n    attributes: {\n      \"session.id\": SESSION_ID,\n      \"user.id\": userId,              // Track user\n      \"metadata.environment\": \"prod\",  // Custom metadata\n    },\n  }\n);\n```\n\n## Anti-Pattern: Don't Create Wrappers\n\n❌ **Don't do this:**\n```typescript\n// Unnecessary wrapper\nexport function withSessionTracking(fn) {\n  return withSpan(fn, { attributes: { \"session.id\": SESSION_ID } });\n}\n```\n\n✅ **Do this instead:**\n```typescript\n// Use withSpan directly\nimport { withSpan } from \"@arizeai/openinference-core\";\nimport { SESSION_ID } from \"./instrumentation\";\n\nconst handler = withSpan(fn, {\n  attributes: { \"session.id\": SESSION_ID }\n});\n```\n\n## Alternative: Context API Pattern\n\nFor web servers or complex async flows where you need to propagate session IDs through middleware, you can use the Context API:\n\n```typescript\nimport { context } from \"@opentelemetry/api\";\nimport { setSession } from \"@arizeai/openinference-core\";\n\nawait context.with(\n  setSession(context.active(), { sessionId: \"user_123_conv_456\" }),\n  async () =\u003e {\n    const response = await llm.invoke(prompt);\n  }\n);\n```\n\n**Use Context API when:**\n- Building web servers with middleware chains\n- Session ID needs to flow through many async boundaries\n- You don't control the call stack (e.g., framework-provided handlers)\n\n**Use withSpan when:**\n- Building CLI apps or scripts\n- You control the function call points\n- Simpler, more explicit code is preferred\n\n## Related\n\n- `fundamentals-universal-attributes.md` - Other universal attributes (user.id, metadata)\n- `span-chain.md` - CHAIN span specification\n- `sessions-python.md` - Python session tracking patterns\n","references/setup-python.md":"# Phoenix Tracing: Python Setup\n\n**Setup Phoenix tracing in Python with `arize-phoenix-otel`.**\n\n## Metadata\n\n| Attribute  | Value                               |\n| ---------- | ----------------------------------- |\n| Priority   | Critical - required for all tracing |\n| Setup Time | \u003c5 min                              |\n\n## Quick Start (3 lines)\n\n```python\nfrom phoenix.otel import register\nregister(project_name=\"my-app\", auto_instrument=True)\n```\n\n**Connects to `http://localhost:6006`, auto-instruments all supported libraries.**\n\n## Installation\n\n```bash\npip install arize-phoenix-otel\n```\n\n**Supported:** Python 3.10-3.13\n\n## Configuration\n\n### Environment Variables (Recommended)\n\n```bash\nexport PHOENIX_API_KEY=\"your-api-key\"  # Required for Phoenix Cloud\nexport PHOENIX_COLLECTOR_ENDPOINT=\"http://localhost:6006\"  # Or Cloud URL\nexport PHOENIX_PROJECT_NAME=\"my-app\"  # Optional\n```\n\n### Python Code\n\n```python\nfrom phoenix.otel import register\n\ntracer_provider = register(\n    project_name=\"my-app\",              # Project name\n    endpoint=\"http://localhost:6006\",   # Phoenix endpoint\n    auto_instrument=True,               # Auto-instrument supported libs\n    batch=True,                         # Batch processing (default: True)\n)\n```\n\n**Parameters:**\n\n- `project_name`: Project name (overrides `PHOENIX_PROJECT_NAME`)\n- `endpoint`: Phoenix URL (overrides `PHOENIX_COLLECTOR_ENDPOINT`)\n- `auto_instrument`: Enable auto-instrumentation (default: False)\n- `batch`: Use BatchSpanProcessor (default: True, production-recommended)\n- `protocol`: `\"http/protobuf\"` (default) or `\"grpc\"`\n\n## Auto-Instrumentation\n\nInstall instrumentors for your frameworks:\n\n```bash\npip install openinference-instrumentation-openai      # OpenAI SDK\npip install openinference-instrumentation-langchain   # LangChain\npip install openinference-instrumentation-llama-index # LlamaIndex\n# ... install others as needed\n```\n\nThen enable auto-instrumentation:\n\n```python\nregister(project_name=\"my-app\", auto_instrument=True)\n```\n\nPhoenix discovers and instruments all installed OpenInference packages automatically.\n\n## Batch Processing (Production)\n\nEnabled by default. Configure via environment variables:\n\n```bash\nexport OTEL_BSP_SCHEDULE_DELAY=5000           # Batch every 5s\nexport OTEL_BSP_MAX_QUEUE_SIZE=2048           # Queue 2048 spans\nexport OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512     # Send 512 spans/batch\n```\n\n**Link:** https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/\n\n## Verification\n\n1. Open Phoenix UI: `http://localhost:6006`\n2. Navigate to your project\n3. Run your application\n4. Check for traces (appear within batch delay)\n\n## Troubleshooting\n\n**No traces:**\n\n- Verify `PHOENIX_COLLECTOR_ENDPOINT` matches Phoenix server\n- Set `PHOENIX_API_KEY` for Phoenix Cloud\n- Confirm instrumentors installed\n\n**Missing attributes:**\n\n- Check span kind (see rules/ directory)\n- Verify attribute names (see rules/ directory)\n\n## Example\n\n```python\nfrom phoenix.otel import register\nfrom openai import OpenAI\n\n# Enable tracing with auto-instrumentation\nregister(project_name=\"my-chatbot\", auto_instrument=True)\n\n# OpenAI automatically instrumented\nclient = OpenAI()\nresponse = client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\n```\n\n## API Reference\n\n- [Python OTEL API Docs](https://arize-phoenix.readthedocs.io/projects/otel/en/latest/)\n- [Python Client API Docs](https://arize-phoenix.readthedocs.io/projects/client/en/latest/)\n","references/setup-typescript.md":"# TypeScript Setup\n\nSetup Phoenix tracing in TypeScript/JavaScript with `@arizeai/phoenix-otel`.\n\n## Metadata\n\n| Attribute | Value |\n|-----------|-------|\n| Priority | Critical - required for all tracing |\n| Setup Time | \u003c5 min |\n\n## Quick Start\n\n```bash\nnpm install @arizeai/phoenix-otel\n```\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\nregister({ projectName: \"my-app\" });\n```\n\nConnects to `http://localhost:6006` by default.\n\n## Configuration\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({\n  projectName: \"my-app\",\n  url: \"http://localhost:6006\",\n  apiKey: process.env.PHOENIX_API_KEY,\n  batch: true\n});\n```\n\n**Environment variables:**\n\n```bash\nexport PHOENIX_API_KEY=\"your-api-key\"\nexport PHOENIX_COLLECTOR_ENDPOINT=\"http://localhost:6006\"\nexport PHOENIX_PROJECT_NAME=\"my-app\"\n```\n\n## ESM vs CommonJS\n\n**CommonJS (automatic):**\n\n```javascript\nconst { register } = require(\"@arizeai/phoenix-otel\");\nregister({ projectName: \"my-app\" });\n\nconst OpenAI = require(\"openai\");\n```\n\n**ESM (manual instrumentation required):**\n\n```typescript\nimport { register, registerInstrumentations } from \"@arizeai/phoenix-otel\";\nimport { OpenAIInstrumentation } from \"@arizeai/openinference-instrumentation-openai\";\nimport OpenAI from \"openai\";\n\nregister({ projectName: \"my-app\" });\n\nconst instrumentation = new OpenAIInstrumentation();\ninstrumentation.manuallyInstrument(OpenAI);\nregisterInstrumentations({ instrumentations: [instrumentation] });\n```\n\n**Why:** ESM imports are hoisted, so `manuallyInstrument()` is needed.\n\n## Framework Integration\n\n**Next.js (App Router):**\n\n```typescript\n// instrumentation.ts\nexport async function register() {\n  if (process.env.NEXT_RUNTIME === \"nodejs\") {\n    const { register } = await import(\"@arizeai/phoenix-otel\");\n    register({ projectName: \"my-nextjs-app\" });\n  }\n}\n```\n\n**Express.js:**\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({ projectName: \"my-express-app\" });\n\nconst app = express();\n```\n\n## Flushing Spans Before Exit\n\n**CRITICAL:** Spans may not be exported if still queued in the processor when your process exits. Call `provider.shutdown()` to explicitly flush before exit.\n\n**Standard pattern:**\n\n```typescript\nconst provider = register({\n  projectName: \"my-app\",\n  batch: true,\n});\n\nasync function main() {\n  await doWork();\n  await provider.shutdown();  // Flush spans before exit\n}\n\nmain().catch(async (error) =\u003e {\n  console.error(error);\n  await provider.shutdown();  // Flush on error too\n  process.exit(1);\n});\n```\n\n**Alternative:**\n\n```typescript\n// Use batch: false for immediate export (no shutdown needed)\nregister({\n  projectName: \"my-app\",\n  batch: false,\n});\n```\n\nFor production patterns including graceful termination, see `production-typescript.md`.\n\n## Verification\n\n1. Open Phoenix UI: `http://localhost:6006`\n2. Run your application\n3. Check for traces in your project\n\n**Enable diagnostic logging:**\n\n```typescript\nimport { DiagLogLevel, register } from \"@arizeai/phoenix-otel\";\n\nregister({\n  projectName: \"my-app\",\n  diagLogLevel: DiagLogLevel.DEBUG,\n});\n```\n\n## Troubleshooting\n\n**No traces:**\n- Verify `PHOENIX_COLLECTOR_ENDPOINT` is correct\n- Set `PHOENIX_API_KEY` for Phoenix Cloud\n- For ESM: Ensure `manuallyInstrument()` is called\n- **With `batch: true`:** Call `provider.shutdown()` before exit to flush queued spans (see Flushing Spans section)\n\n**Traces missing:**\n- With `batch: true`: Call `await provider.shutdown()` before process exit to flush queued spans\n- Alternative: Set `batch: false` for immediate export (no shutdown needed)\n\n**Missing attributes:**\n- Check instrumentation is registered (ESM requires manual setup)\n- See `instrumentation-auto-typescript.md`\n\n## See Also\n\n- **Auto-instrumentation:** `instrumentation-auto-typescript.md`\n- **Manual instrumentation:** `instrumentation-manual-typescript.md`\n- **API docs:** https://arize-ai.github.io/phoenix/\n","references/span-agent.md":"# AGENT Spans\n\nAGENT spans represent autonomous reasoning blocks (ReAct agents, planning loops, multi-step decision making).\n\n**Required:** `openinference.span.kind` = \"AGENT\"\n\n## Example\n\n```json\n{\n  \"openinference.span.kind\": \"AGENT\",\n  \"input.value\": \"Book a flight to New York for next Monday\",\n  \"output.value\": \"I've booked flight AA123 departing Monday at 9:00 AM\"\n}\n```\n","references/span-chain.md":"# CHAIN Spans\n\n## Purpose\n\nCHAIN spans represent orchestration layers in your application (LangChain chains, custom workflows, application entry points). Often used as root spans.\n\n## Required Attributes\n\n| Attribute                 | Type   | Description     | Required |\n| ------------------------- | ------ | --------------- | -------- |\n| `openinference.span.kind` | String | Must be \"CHAIN\" | Yes      |\n\n## Common Attributes\n\nCHAIN spans typically use [Universal Attributes](fundamentals-universal-attributes.md):\n\n- `input.value` - Input to the chain (user query, request payload)\n- `output.value` - Output from the chain (final response)\n- `input.mime_type` / `output.mime_type` - Format indicators\n\n## Example: Root Chain\n\n```json\n{\n  \"openinference.span.kind\": \"CHAIN\",\n  \"input.value\": \"{\\\"question\\\": \\\"What is the capital of France?\\\"}\",\n  \"input.mime_type\": \"application/json\",\n  \"output.value\": \"{\\\"answer\\\": \\\"The capital of France is Paris.\\\", \\\"sources\\\": [\\\"doc_123\\\"]}\",\n  \"output.mime_type\": \"application/json\",\n  \"session.id\": \"session_abc123\",\n  \"user.id\": \"user_xyz789\"\n}\n```\n\n## Example: Nested Sub-Chain\n\n```json\n{\n  \"openinference.span.kind\": \"CHAIN\",\n  \"input.value\": \"Summarize this document: ...\",\n  \"output.value\": \"This document discusses...\"\n}\n```\n","references/span-embedding.md":"# EMBEDDING Spans\n\n## Purpose\n\nEMBEDDING spans represent vector generation operations (text-to-vector conversion for semantic search).\n\n## Required Attributes\n\n| Attribute | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `openinference.span.kind` | String | Must be \"EMBEDDING\" | Yes |\n| `embedding.model_name` | String | Embedding model identifier | Recommended |\n\n## Attribute Reference\n\n### Single Embedding\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `embedding.model_name` | String | Embedding model identifier |\n| `embedding.text` | String | Input text to embed |\n| `embedding.vector` | String (JSON array) | Generated embedding vector |\n\n**Example:**\n```json\n{\n  \"embedding.model_name\": \"text-embedding-ada-002\",\n  \"embedding.text\": \"What is machine learning?\",\n  \"embedding.vector\": \"[0.023, -0.012, 0.045, ..., 0.001]\"\n}\n```\n\n### Batch Embeddings\n\n| Attribute Pattern | Type | Description |\n|-------------------|------|-------------|\n| `embedding.embeddings.{i}.embedding.text` | String | Text at index i |\n| `embedding.embeddings.{i}.embedding.vector` | String (JSON array) | Vector at index i |\n\n**Example:**\n```json\n{\n  \"embedding.model_name\": \"text-embedding-ada-002\",\n  \"embedding.embeddings.0.embedding.text\": \"First document\",\n  \"embedding.embeddings.0.embedding.vector\": \"[0.1, 0.2, 0.3, ..., 0.5]\",\n  \"embedding.embeddings.1.embedding.text\": \"Second document\",\n  \"embedding.embeddings.1.embedding.vector\": \"[0.6, 0.7, 0.8, ..., 0.9]\"\n}\n```\n\n### Vector Format\n\nVectors stored as JSON array strings:\n- Dimensions: Typically 384, 768, 1536, or 3072\n- Format: `\"[0.123, -0.456, 0.789, ...]\"`\n- Precision: Usually 3-6 decimal places\n\n**Storage Considerations:**\n- Large vectors can significantly increase trace size\n- Consider omitting vectors in production (keep `embedding.text` for debugging)\n- Use separate vector database for actual similarity search\n\n## Examples\n\n### Single Embedding\n\n```json\n{\n  \"openinference.span.kind\": \"EMBEDDING\",\n  \"embedding.model_name\": \"text-embedding-ada-002\",\n  \"embedding.text\": \"What is machine learning?\",\n  \"embedding.vector\": \"[0.023, -0.012, 0.045, ..., 0.001]\",\n  \"input.value\": \"What is machine learning?\",\n  \"output.value\": \"[0.023, -0.012, 0.045, ..., 0.001]\"\n}\n```\n\n### Batch Embeddings\n\n```json\n{\n  \"openinference.span.kind\": \"EMBEDDING\",\n  \"embedding.model_name\": \"text-embedding-ada-002\",\n  \"embedding.embeddings.0.embedding.text\": \"First document\",\n  \"embedding.embeddings.0.embedding.vector\": \"[0.1, 0.2, 0.3]\",\n  \"embedding.embeddings.1.embedding.text\": \"Second document\",\n  \"embedding.embeddings.1.embedding.vector\": \"[0.4, 0.5, 0.6]\",\n  \"embedding.embeddings.2.embedding.text\": \"Third document\",\n  \"embedding.embeddings.2.embedding.vector\": \"[0.7, 0.8, 0.9]\"\n}\n```\n","references/span-evaluator.md":"# EVALUATOR Spans\n\n## Purpose\n\nEVALUATOR spans represent quality assessment operations (answer relevance, faithfulness, hallucination detection).\n\n## Required Attributes\n\n| Attribute | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `openinference.span.kind` | String | Must be \"EVALUATOR\" | Yes |\n\n## Common Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `input.value` | String | Content being evaluated |\n| `output.value` | String | Evaluation result (score, label, explanation) |\n| `metadata.evaluator_name` | String | Evaluator identifier |\n| `metadata.score` | Float | Numeric score (0-1) |\n| `metadata.label` | String | Categorical label (relevant/irrelevant) |\n\n## Example: Answer Relevance\n\n```json\n{\n  \"openinference.span.kind\": \"EVALUATOR\",\n  \"input.value\": \"{\\\"question\\\": \\\"What is the capital of France?\\\", \\\"answer\\\": \\\"The capital of France is Paris.\\\"}\",\n  \"input.mime_type\": \"application/json\",\n  \"output.value\": \"0.95\",\n  \"metadata.evaluator_name\": \"answer_relevance\",\n  \"metadata.score\": 0.95,\n  \"metadata.label\": \"relevant\",\n  \"metadata.explanation\": \"Answer directly addresses the question with correct information\"\n}\n```\n\n## Example: Faithfulness Check\n\n```json\n{\n  \"openinference.span.kind\": \"EVALUATOR\",\n  \"input.value\": \"{\\\"context\\\": \\\"Paris is in France.\\\", \\\"answer\\\": \\\"Paris is the capital of France.\\\"}\",\n  \"input.mime_type\": \"application/json\",\n  \"output.value\": \"0.5\",\n  \"metadata.evaluator_name\": \"faithfulness\",\n  \"metadata.score\": 0.5,\n  \"metadata.label\": \"partially_faithful\",\n  \"metadata.explanation\": \"Answer makes unsupported claim about Paris being the capital\"\n}\n```\n","references/span-guardrail.md":"# GUARDRAIL Spans\n\n## Purpose\n\nGUARDRAIL spans represent safety and policy checks (content moderation, PII detection, toxicity scoring).\n\n## Required Attributes\n\n| Attribute | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `openinference.span.kind` | String | Must be \"GUARDRAIL\" | Yes |\n\n## Common Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `input.value` | String | Content being checked |\n| `output.value` | String | Guardrail result (allowed/blocked/flagged) |\n| `metadata.guardrail_type` | String | Type of check (toxicity, pii, bias) |\n| `metadata.score` | Float | Safety score (0-1) |\n| `metadata.threshold` | Float | Threshold for blocking |\n\n## Example: Content Moderation\n\n```json\n{\n  \"openinference.span.kind\": \"GUARDRAIL\",\n  \"input.value\": \"User message: I want to build a bomb\",\n  \"output.value\": \"BLOCKED\",\n  \"metadata.guardrail_type\": \"content_moderation\",\n  \"metadata.score\": 0.95,\n  \"metadata.threshold\": 0.7,\n  \"metadata.categories\": \"[\\\"violence\\\", \\\"weapons\\\"]\",\n  \"metadata.action\": \"block_and_log\"\n}\n```\n\n## Example: PII Detection\n\n```json\n{\n  \"openinference.span.kind\": \"GUARDRAIL\",\n  \"input.value\": \"My SSN is 123-45-6789\",\n  \"output.value\": \"FLAGGED\",\n  \"metadata.guardrail_type\": \"pii_detection\",\n  \"metadata.detected_pii\": \"[\\\"ssn\\\"]\",\n  \"metadata.redacted_output\": \"My SSN is [REDACTED]\"\n}\n```\n","references/span-llm.md":"# LLM Spans\n\nRepresent calls to language models (OpenAI, Anthropic, local models, etc.).\n\n## Required Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `openinference.span.kind` | String | Must be \"LLM\" |\n| `llm.model_name` | String | Model identifier (e.g., \"gpt-4\", \"claude-3-5-sonnet-20241022\") |\n\n## Key Attributes\n\n| Category | Attributes | Example |\n|----------|------------|---------|\n| **Model** | `llm.model_name`, `llm.provider` | \"gpt-4-turbo\", \"openai\" |\n| **Tokens** | `llm.token_count.prompt`, `llm.token_count.completion`, `llm.token_count.total` | 25, 8, 33 |\n| **Cost** | `llm.cost.prompt`, `llm.cost.completion`, `llm.cost.total` | 0.0021, 0.0045, 0.0066 |\n| **Parameters** | `llm.invocation_parameters` (JSON) | `{\"temperature\": 0.7, \"max_tokens\": 1024}` |\n| **Messages** | `llm.input_messages.{i}.*`, `llm.output_messages.{i}.*` | See examples below |\n| **Tools** | `llm.tools.{i}.tool.json_schema` | Function definitions |\n\n## Cost Tracking\n\n**Core attributes:**\n- `llm.cost.prompt` - Total input cost (USD)\n- `llm.cost.completion` - Total output cost (USD)\n- `llm.cost.total` - Total cost (USD)\n\n**Detailed cost breakdown:**\n- `llm.cost.prompt_details.{input,cache_read,cache_write,audio}` - Input cost components\n- `llm.cost.completion_details.{output,reasoning,audio}` - Output cost components\n\n## Messages\n\n**Input messages:**\n- `llm.input_messages.{i}.message.role` - \"user\", \"assistant\", \"system\", \"tool\"\n- `llm.input_messages.{i}.message.content` - Text content\n- `llm.input_messages.{i}.message.contents.{j}` - Multimodal (text + images)\n- `llm.input_messages.{i}.message.tool_calls` - Tool invocations\n\n**Output messages:** Same structure as input messages.\n\n## Example: Basic LLM Call\n\n```json\n{\n  \"openinference.span.kind\": \"LLM\",\n  \"llm.model_name\": \"claude-3-5-sonnet-20241022\",\n  \"llm.invocation_parameters\": \"{\\\"temperature\\\": 0.7, \\\"max_tokens\\\": 1024}\",\n  \"llm.input_messages.0.message.role\": \"system\",\n  \"llm.input_messages.0.message.content\": \"You are a helpful assistant.\",\n  \"llm.input_messages.1.message.role\": \"user\",\n  \"llm.input_messages.1.message.content\": \"What is the capital of France?\",\n  \"llm.output_messages.0.message.role\": \"assistant\",\n  \"llm.output_messages.0.message.content\": \"The capital of France is Paris.\",\n  \"llm.token_count.prompt\": 25,\n  \"llm.token_count.completion\": 8,\n  \"llm.token_count.total\": 33\n}\n```\n\n## Example: LLM with Tool Calls\n\n```json\n{\n  \"openinference.span.kind\": \"LLM\",\n  \"llm.model_name\": \"gpt-4-turbo\",\n  \"llm.input_messages.0.message.content\": \"What's the weather in SF?\",\n  \"llm.output_messages.0.message.tool_calls.0.tool_call.function.name\": \"get_weather\",\n  \"llm.output_messages.0.message.tool_calls.0.tool_call.function.arguments\": \"{\\\"location\\\": \\\"San Francisco\\\"}\",\n  \"llm.tools.0.tool.json_schema\": \"{\\\"type\\\": \\\"function\\\", \\\"function\\\": {\\\"name\\\": \\\"get_weather\\\"}}\"\n}\n```\n\n## See Also\n\n- **Instrumentation:** `instrumentation-auto-python.md`, `instrumentation-manual-python.md`\n- **Full spec:** https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md\n","references/span-reranker.md":"# RERANKER Spans\n\n## Purpose\n\nRERANKER spans represent reordering of retrieved documents (Cohere Rerank, cross-encoder models).\n\n## Required Attributes\n\n| Attribute | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `openinference.span.kind` | String | Must be \"RERANKER\" | Yes |\n\n## Attribute Reference\n\n### Reranker Parameters\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `reranker.model_name` | String | Reranker model identifier |\n| `reranker.query` | String | Query used for reranking |\n| `reranker.top_k` | Integer | Number of documents to return |\n\n### Input Documents\n\n| Attribute Pattern | Type | Description |\n|-------------------|------|-------------|\n| `reranker.input_documents.{i}.document.id` | String | Input document ID |\n| `reranker.input_documents.{i}.document.content` | String | Input document content |\n| `reranker.input_documents.{i}.document.score` | Float | Original retrieval score |\n| `reranker.input_documents.{i}.document.metadata` | String (JSON) | Document metadata |\n\n### Output Documents\n\n| Attribute Pattern | Type | Description |\n|-------------------|------|-------------|\n| `reranker.output_documents.{i}.document.id` | String | Output document ID (reordered) |\n| `reranker.output_documents.{i}.document.content` | String | Output document content |\n| `reranker.output_documents.{i}.document.score` | Float | New reranker score |\n| `reranker.output_documents.{i}.document.metadata` | String (JSON) | Document metadata |\n\n### Score Comparison\n\nInput scores (from retriever) vs. output scores (from reranker):\n\n```json\n{\n  \"reranker.input_documents.0.document.id\": \"doc_A\",\n  \"reranker.input_documents.0.document.score\": 0.7,\n  \"reranker.input_documents.1.document.id\": \"doc_B\",\n  \"reranker.input_documents.1.document.score\": 0.9,\n  \"reranker.output_documents.0.document.id\": \"doc_B\",\n  \"reranker.output_documents.0.document.score\": 0.95,\n  \"reranker.output_documents.1.document.id\": \"doc_A\",\n  \"reranker.output_documents.1.document.score\": 0.85\n}\n```\n\nIn this example:\n- Input: doc_B (0.9) ranked higher than doc_A (0.7)\n- Output: doc_B still highest but both scores increased\n- Reranker confirmed retriever's ordering but refined scores\n\n## Examples\n\n### Complete Reranking Example\n\n```json\n{\n  \"openinference.span.kind\": \"RERANKER\",\n  \"reranker.model_name\": \"cohere-rerank-v2\",\n  \"reranker.query\": \"What is machine learning?\",\n  \"reranker.top_k\": 2,\n  \"reranker.input_documents.0.document.id\": \"doc_123\",\n  \"reranker.input_documents.0.document.content\": \"Machine learning is a subset...\",\n  \"reranker.input_documents.1.document.id\": \"doc_456\",\n  \"reranker.input_documents.1.document.content\": \"Supervised learning algorithms...\",\n  \"reranker.input_documents.2.document.id\": \"doc_789\",\n  \"reranker.input_documents.2.document.content\": \"Neural networks are...\",\n  \"reranker.output_documents.0.document.id\": \"doc_456\",\n  \"reranker.output_documents.0.document.content\": \"Supervised learning algorithms...\",\n  \"reranker.output_documents.0.document.score\": 0.95,\n  \"reranker.output_documents.1.document.id\": \"doc_123\",\n  \"reranker.output_documents.1.document.content\": \"Machine learning is a subset...\",\n  \"reranker.output_documents.1.document.score\": 0.88\n}\n```\n","references/span-retriever.md":"# RETRIEVER Spans\n\n## Purpose\n\nRETRIEVER spans represent document/context retrieval operations (vector DB queries, semantic search, keyword search).\n\n## Required Attributes\n\n| Attribute | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `openinference.span.kind` | String | Must be \"RETRIEVER\" | Yes |\n\n## Attribute Reference\n\n### Query\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `input.value` | String | Search query text |\n\n### Document Schema\n\n| Attribute Pattern | Type | Description |\n|-------------------|------|-------------|\n| `retrieval.documents.{i}.document.id` | String | Unique document identifier |\n| `retrieval.documents.{i}.document.content` | String | Document text content |\n| `retrieval.documents.{i}.document.score` | Float | Relevance score (0-1 or distance) |\n| `retrieval.documents.{i}.document.metadata` | String (JSON) | Document metadata |\n\n### Flattening Pattern for Documents\n\nDocuments are flattened using zero-indexed notation:\n\n```\nretrieval.documents.0.document.id\nretrieval.documents.0.document.content\nretrieval.documents.0.document.score\nretrieval.documents.1.document.id\nretrieval.documents.1.document.content\nretrieval.documents.1.document.score\n...\n```\n\n### Document Metadata\n\nCommon metadata fields (stored as JSON string):\n\n```json\n{\n  \"source\": \"knowledge_base.pdf\",\n  \"page\": 42,\n  \"section\": \"Introduction\",\n  \"author\": \"Jane Doe\",\n  \"created_at\": \"2024-01-15\",\n  \"url\": \"https://example.com/doc\",\n  \"chunk_id\": \"chunk_123\"\n}\n```\n\n**Example with metadata:**\n```json\n{\n  \"retrieval.documents.0.document.id\": \"doc_123\",\n  \"retrieval.documents.0.document.content\": \"Machine learning is a method of data analysis...\",\n  \"retrieval.documents.0.document.score\": 0.92,\n  \"retrieval.documents.0.document.metadata\": \"{\\\"source\\\": \\\"ml_textbook.pdf\\\", \\\"page\\\": 15, \\\"chapter\\\": \\\"Introduction\\\"}\"\n}\n```\n\n### Ordering\n\nDocuments are ordered by index (0, 1, 2, ...). Typically:\n- Index 0 = highest scoring document\n- Index 1 = second highest\n- etc.\n\nPreserve retrieval order in your flattened attributes.\n\n### Large Document Handling\n\nFor very long documents:\n- Consider truncating `document.content` to first N characters\n- Store full content in separate document store\n- Use `document.id` to reference full content\n\n## Examples\n\n### Basic Vector Search\n\n```json\n{\n  \"openinference.span.kind\": \"RETRIEVER\",\n  \"input.value\": \"What is machine learning?\",\n  \"retrieval.documents.0.document.id\": \"doc_123\",\n  \"retrieval.documents.0.document.content\": \"Machine learning is a subset of artificial intelligence...\",\n  \"retrieval.documents.0.document.score\": 0.92,\n  \"retrieval.documents.0.document.metadata\": \"{\\\"source\\\": \\\"textbook.pdf\\\", \\\"page\\\": 42}\",\n  \"retrieval.documents.1.document.id\": \"doc_456\",\n  \"retrieval.documents.1.document.content\": \"Machine learning algorithms learn patterns from data...\",\n  \"retrieval.documents.1.document.score\": 0.87,\n  \"retrieval.documents.1.document.metadata\": \"{\\\"source\\\": \\\"article.html\\\", \\\"author\\\": \\\"Jane Doe\\\"}\",\n  \"retrieval.documents.2.document.id\": \"doc_789\",\n  \"retrieval.documents.2.document.content\": \"Supervised learning is a type of machine learning...\",\n  \"retrieval.documents.2.document.score\": 0.81,\n  \"retrieval.documents.2.document.metadata\": \"{\\\"source\\\": \\\"wiki.org\\\"}\",\n  \"metadata.retriever_type\": \"vector_search\",\n  \"metadata.vector_db\": \"pinecone\",\n  \"metadata.top_k\": 3\n}\n```\n","references/span-tool.md":"# TOOL Spans\n\n## Purpose\n\nTOOL spans represent external tool or function invocations (API calls, database queries, calculators, custom functions).\n\n## Required Attributes\n\n| Attribute                 | Type   | Description        | Required    |\n| ------------------------- | ------ | ------------------ | ----------- |\n| `openinference.span.kind` | String | Must be \"TOOL\"     | Yes         |\n| `tool.name`               | String | Tool/function name | Recommended |\n\n## Attribute Reference\n\n### Tool Execution Attributes\n\n| Attribute          | Type          | Description                                |\n| ------------------ | ------------- | ------------------------------------------ |\n| `tool.name`        | String        | Tool/function name                         |\n| `tool.description` | String        | Tool purpose/description                   |\n| `tool.parameters`  | String (JSON) | JSON schema defining the tool's parameters |\n| `input.value`      | String (JSON) | Actual input values passed to the tool     |\n| `output.value`     | String        | Tool output/result                         |\n| `output.mime_type` | String        | Result content type (e.g., \"application/json\") |\n\n## Examples\n\n### API Call Tool\n\n```json\n{\n  \"openinference.span.kind\": \"TOOL\",\n  \"tool.name\": \"get_weather\",\n  \"tool.description\": \"Fetches current weather for a location\",\n  \"tool.parameters\": \"{\\\"type\\\": \\\"object\\\", \\\"properties\\\": {\\\"location\\\": {\\\"type\\\": \\\"string\\\"}, \\\"units\\\": {\\\"type\\\": \\\"string\\\", \\\"enum\\\": [\\\"celsius\\\", \\\"fahrenheit\\\"]}}, \\\"required\\\": [\\\"location\\\"]}\",\n  \"input.value\": \"{\\\"location\\\": \\\"San Francisco\\\", \\\"units\\\": \\\"celsius\\\"}\",\n  \"output.value\": \"{\\\"temperature\\\": 18, \\\"conditions\\\": \\\"partly cloudy\\\"}\"\n}\n```\n\n### Calculator Tool\n\n```json\n{\n  \"openinference.span.kind\": \"TOOL\",\n  \"tool.name\": \"calculator\",\n  \"tool.description\": \"Performs mathematical calculations\",\n  \"tool.parameters\": \"{\\\"type\\\": \\\"object\\\", \\\"properties\\\": {\\\"expression\\\": {\\\"type\\\": \\\"string\\\", \\\"description\\\": \\\"Math expression to evaluate\\\"}}, \\\"required\\\": [\\\"expression\\\"]}\",\n  \"input.value\": \"{\\\"expression\\\": \\\"2 + 2\\\"}\",\n  \"output.value\": \"4\"\n}\n```\n\n### Database Query Tool\n\n```json\n{\n  \"openinference.span.kind\": \"TOOL\",\n  \"tool.name\": \"sql_query\",\n  \"tool.description\": \"Executes SQL query on user database\",\n  \"tool.parameters\": \"{\\\"type\\\": \\\"object\\\", \\\"properties\\\": {\\\"query\\\": {\\\"type\\\": \\\"string\\\", \\\"description\\\": \\\"SQL query to execute\\\"}}, \\\"required\\\": [\\\"query\\\"]}\",\n  \"input.value\": \"{\\\"query\\\": \\\"SELECT * FROM users WHERE id = 123\\\"}\",\n  \"output.value\": \"[{\\\"id\\\": 123, \\\"name\\\": \\\"Alice\\\", \\\"email\\\": \\\"alice@example.com\\\"}]\",\n  \"output.mime_type\": \"application/json\"\n}\n```\n"},"import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/tree/541b7819d8c3545c6df122491af4fa1eae415779/plugins/phoenix/skills/phoenix-tracing"}},"content_hash":[244,50,155,67,179,89,162,90,127,132,26,211,145,133,64,92,116,29,250,137,6,191,255,252,75,27,155,143,222,85,214,166],"trust_level":"unsigned","yanked":false}