AutoGineer
Generated banner for Phoenix Tracing
Generated logo for Phoenix Tracing

Phoenix Tracing

GitHubOfficialFirst committed by jimbobbennettDistributed by GitHub

  • Skill
  • Tool integration
  • Data and AI
  • Apache-2.0
  • Low risk
Download ZIP

From the author

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

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Phoenix Tracing provides a structured framework for implementing observability in LLM-based applications. It covers the full lifecycle of trace management, including setup, auto and manual instrumentation, span type definitions, and production deployment. The skill offers specific guidance for both Python and TypeScript environments, enabling developers to capture detailed telemetry for LLM calls, retrieval processes, agent reasoning, and evaluation feedback.

What it does

  • Provides setup instructions for Python and TypeScript SDKs.
  • Defines OpenInference semantic conventions for various span types like LLM, retriever, and agent.
  • Supports both auto-instrumentation and manual custom span creation.
  • Enables feedback collection through annotations on traces, spans, documents, and sessions.
  • Offers guidance on production concerns such as batch processing and PII masking.
  • Facilitates organization of trace data by projects and user sessions.

When to use it

  • When you need to implement observability for LLM applications.
  • When you want to track multi-step workflows or agent reasoning processes.
  • When you need to add custom metadata or feedback annotations to your traces.
  • When preparing your LLM application for production monitoring.
  • When you need to ensure your instrumentation follows OpenInference standards.

Advantages

  • Standardized tracing using OpenInference conventions.
  • Supports both Python and TypeScript ecosystems.
  • Granular control over span types and custom attributes.
  • Built-in support for human, LLM, and code-based feedback annotations.
  • Comprehensive documentation for both development and production deployment.

Usage examples

“How do I set up Phoenix tracing in my Python project?”
The agent provides the installation steps for the arize-phoenix-otel package and demonstrates how to configure the endpoint to begin capturing traces.
“How can I add a custom span for an LLM call in TypeScript?”
The agent guides you through using the @arizeai/phoenix-otel library to wrap your LLM API calls with the appropriate span attributes.
“How do I add human feedback to a specific span?”
The agent shows the code pattern for using the client.spans.add_span_annotation method, including how to specify the label, score, and explanation.
“What are the best practices for production tracing?”
The agent explains how to implement batch processing and PII masking to ensure efficient and secure trace data collection in a production environment.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/github/phoenix-tracing/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip phoenix-tracing.zip -d .agents/skills

Documentation by jimbobbennett

Phoenix Tracing

Comprehensive guide for instrumenting LLM applications with OpenInference tracing in Phoenix. Contains reference files covering setup, instrumentation, span types, and production deployment.

When to Apply

Reference these guidelines when:

  • Setting up Phoenix tracing (Python or TypeScript)

  • Creating custom spans for LLM operations

  • Adding attributes following OpenInference conventions

  • Deploying tracing to production

  • Querying and analyzing trace data

Reference Categories

PriorityCategoryDescriptionPrefix
1SetupInstallation and configurationsetup-*
2InstrumentationAuto and manual tracinginstrumentation-*
3Span Types9 span kinds with attributesspan-*
4OrganizationProjects and sessionsprojects-*, sessions-*
5EnrichmentCustom metadatametadata-*
6ProductionBatch processing, maskingproduction-*
7FeedbackAnnotations and evaluationannotations-*

Quick Reference

1. Setup (START HERE)
2. Instrumentation
3. Span Types (with full attribute schemas)
4. Organization
5. Enrichment
6. Production (CRITICAL)
7. Feedback
Reference Files

Common Workflows

  • Quick Start: setup-{lang} → instrumentation-auto-{lang} → Check Phoenix

  • Custom Spans: setup-{lang} → instrumentation-manual-{lang} → span-{type}

  • Session Tracking: sessions-{lang} for conversation grouping patterns

  • Production: production-{lang} for batching, masking, and deployment

How to Use This Skill

Navigation Patterns:

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

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

Reading Order:

  1. Start with setup-{lang} for your language

  2. Choose instrumentation-auto-{lang} OR instrumentation-manual-{lang}

  3. Reference span-{type} files as needed for specific operations

  4. See fundamentals-* files for attribute specifications

References

Phoenix Documentation:

Python API Documentation:

TypeScript API Documentation:

  • TypeScript Packages - @arizeai/phoenix-otel, @arizeai/phoenix-client, and other TypeScript packages

Files

references/sessions-typescript.md

Sessions (TypeScript)

Track multi-turn conversations by grouping traces with session IDs. Use withSpan directly from @arizeai/openinference-core - no wrappers or custom utilities needed.

Core Concept

Session Pattern:

  1. Generate a unique session.id once at application startup

  2. Export SESSION_ID, import withSpan where needed

  3. Use withSpan to create a parent CHAIN span with session.id for each interaction

  4. All child spans (LLM, TOOL, AGENT, etc.) automatically group under the parent

  5. Query traces by session.id in Phoenix to see all interactions

Implementation (Best Practice)

1. Setup (instrumentation.ts)
import { register } from "@arizeai/phoenix-otel";
import { randomUUID } from "node:crypto";

// Initialize Phoenix
register({
  projectName: "your-app",
  url: process.env.PHOENIX_COLLECTOR_ENDPOINT || "http://localhost:6006",
  apiKey: process.env.PHOENIX_API_KEY,
  batch: true,
});

// Generate and export session ID
export const SESSION_ID = randomUUID();
2. Usage (app code)
import { withSpan } from "@arizeai/openinference-core";
import { SESSION_ID } from "./instrumentation";

// Use withSpan directly - no wrapper needed
const handleInteraction = withSpan(
  async () => {
    const result = await agent.generate({ prompt: userInput });
    return result;
  },
  {
    name: "cli.interaction",
    kind: "CHAIN",
    attributes: { "session.id": SESSION_ID },
  }
);

// Call it
const result = await handleInteraction();
With Input Parameters
const processQuery = withSpan(
  async (query: string) => {
    return await agent.generate({ prompt: query });
  },
  {
    name: "process.query",
    kind: "CHAIN",
    attributes: { "session.id": SESSION_ID },
  }
);

await processQuery("What is 2+2?");

Key Points

Session ID Scope

  • CLI/Desktop Apps: Generate once at process startup

  • Web Servers: Generate per-user session (e.g., on login, store in session storage)

  • Stateless APIs: Accept session.id as a parameter from client

Span Hierarchy
cli.interaction (CHAIN) ← session.id here
├── ai.generateText (AGENT)
│   ├── ai.generateText.doGenerate (LLM)
│   └── ai.toolCall (TOOL)
└── ai.generateText.doGenerate (LLM)

The session.id is only set on the root span. Child spans are automatically grouped by the trace hierarchy.

Querying Sessions
# Get all traces for a session
npx @arizeai/phoenix-cli traces \
  --endpoint http://localhost:6006 \
  --project your-app \
  --format raw \
  --no-progress | \
  jq '.[] | select(.spans[0].attributes["session.id"] == "YOUR-SESSION-ID")'

Dependencies

{
  "dependencies": {
    "@arizeai/openinference-core": "^2.0.5",
    "@arizeai/phoenix-otel": "^0.4.1"
  }
}

Note: @opentelemetry/api is NOT needed - it's only for manual span management.

Why This Pattern?

  1. Simple: Just export SESSION_ID, use withSpan directly - no wrappers

  2. Built-in: withSpan from @arizeai/openinference-core handles everything

  3. Type-safe: Preserves function signatures and type information

  4. Automatic lifecycle: Handles span creation, error tracking, and cleanup

  5. Framework-agnostic: Works with any LLM framework (AI SDK, LangChain, etc.)

  6. No extra deps: Don't need @opentelemetry/api or custom utilities

Adding More Attributes

import { withSpan } from "@arizeai/openinference-core";
import { SESSION_ID } from "./instrumentation";

const handleWithContext = withSpan(
  async (userInput: string) => {
    return await agent.generate({ prompt: userInput });
  },
  {
    name: "cli.interaction",
    kind: "CHAIN",
    attributes: {
      "session.id": SESSION_ID,
      "user.id": userId,              // Track user
      "metadata.environment": "prod",  // Custom metadata
    },
  }
);

Anti-Pattern: Don't Create Wrappers

❌ Don't do this:

// Unnecessary wrapper
export function withSessionTracking(fn) {
  return withSpan(fn, { attributes: { "session.id": SESSION_ID } });
}

✅ Do this instead:

// Use withSpan directly
import { withSpan } from "@arizeai/openinference-core";
import { SESSION_ID } from "./instrumentation";

const handler = withSpan(fn, {
  attributes: { "session.id": SESSION_ID }
});

Alternative: Context API Pattern

For web servers or complex async flows where you need to propagate session IDs through middleware, you can use the Context API:

import { context } from "@opentelemetry/api";
import { setSession } from "@arizeai/openinference-core";

await context.with(
  setSession(context.active(), { sessionId: "user_123_conv_456" }),
  async () => {
    const response = await llm.invoke(prompt);
  }
);

Use Context API when:

  • Building web servers with middleware chains

  • Session ID needs to flow through many async boundaries

  • You don't control the call stack (e.g., framework-provided handlers)

Use withSpan when:

  • Building CLI apps or scripts

  • You control the function call points

  • Simpler, more explicit code is preferred

Related

  • fundamentals-universal-attributes.md - Other universal attributes (user.id, metadata)

  • span-chain.md - CHAIN span specification

  • sessions-python.md - Python session tracking patterns

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Requires Phoenix server. Python skills need arize-phoenix-otel; TypeScript skills need @arizeai/phoenix-otel.

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by
GitHub avatar of jimbobbennettjimbobbennett
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/phoenix-tracing · commit 797337f
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (written by AutoGineer)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
jimbobbennett, stbenjam

AutoGineer is not affiliated with or endorsed by jimbobbennett or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download phoenix-tracing.zip