Skip to main content

This document provides comprehensive guidance on integrating Graphite with Phoenix for distributed tracing and observability.

Table of Contents#

Overview#

Graphite integrates with OpenTelemetry to provide distributed tracing through multiple backends:

  • Phoenix: Local/remote tracing solution ideal for development and debugging
  • Auto: Automatic detection of available tracing endpoints
  • In-Memory: Testing mode without external dependencies

The integration is built on top of OpenTelemetry and automatically instruments:

  • OpenAI API calls
  • LLM interactions
  • Tool executions
  • Workflow orchestration
  • Node operations

Installation#

Core Dependencies#

Grafi includes the following observability dependencies by default:

These are automatically installed when you install Grafi:

Optional Development Dependencies#

For local Phoenix tracing during development:

Configuration#

Docker Compose#

To run Phoenix you can run it on your local machine via docker compose

Environment Variables#

Collector Configuration#

Graphite reads its collector target from its own environment variables ā€” a bare host and a port, used for gRPC export. These default to Phoenixā€™s local gRPC endpoint:

Graphite does not read Phoenixā€™s PHOENIX_* environment variables; equivalently, pass collector_endpoint and collector_port directly to setup_tracing().

Setup Function Parameters#

The setup_tracing() function accepts the following parameters:

  • tracing_options: Backend to use (PHOENIX, AUTO, IN_MEMORY)
  • collector_endpoint: Hostname of the collector (default: ā€œlocalhostā€)
  • collector_port: Port number of the collector (default: 4317)
  • project_name: Name for the tracing project (default: ā€œgrafi-traceā€)

Tracing Options#

Grafi provides three tracing backend options through the TracingOptions enum:

1. PHOENIX - Local/Remote Development#

Use Phoenix for development and debugging:

When to use:

  • Local development and debugging
  • Quick iteration and testing
  • Learning and experimentation
  • Running Phoenix locally or on a remote server

2. AUTO - Automatic Detection#

Let Grafi automatically detect available tracing endpoints:

Detection priority:

  1. Default collector endpoint (if available)
  2. Phoenix endpoint from environment variables
  3. Falls back to in-memory tracing

When to use:

  • Development environments with optional Phoenix
  • CI/CD pipelines
  • Flexible deployment scenarios

3. IN_MEMORY - Testing#

Use in-memory tracing for tests and offline work:

When to use:

  • Unit and integration tests
  • CI/CD without external dependencies
  • Offline development
  • Minimal overhead scenarios

Usage Examples#

Example 1: Basic Setup with AUTO Detection#

Example 2: Development with Local Phoenix#

First, start Phoenix locally:

Then in your code:

Visit http://localhost:6006 to view the Phoenix UI.

Example 3: Testing with In-Memory Tracing#

Example 4: Remote Phoenix Instance#

Example 5: Complete Assistant with Tracing#

Best Practices#

1. Environment-Specific Configuration#

Use different tracing backends for different environments:

2. Early Initialization#

Set up tracing early in your application lifecycle, before creating assistants:

3. Project Naming Conventions#

Use descriptive project names to organize traces:

4. Secure Credential Management#

Never hardcode API keys. Use environment variables or secret management:

5. Graceful Degradation with AUTO Mode#

Use AUTO mode to gracefully degrade when tracing endpoints are unavailable:

6. Testing Isolation#

Use IN_MEMORY mode in tests to avoid external dependencies:

Troubleshooting#

Issue: ā€œPhoenix endpoint is not availableā€#

Symptom: ValueError when using PHOENIX tracing option

Solution:

  1. Ensure Phoenix is running:

  2. Check the endpoint and port are correct:

  3. Use AUTO mode for graceful fallback:

Issue: Connection timeout with Phoenix#

Symptom: Slow startup or timeout errors

Solution:

  1. The endpoint check has a 0.1s timeout, which is normal

  2. Use AUTO mode to automatically fall back:

  3. For PHOENIX mode, ensure the endpoint is reachable:

Issue: OpenAI instrumentation not working#

Symptom: OpenAI calls not showing in traces

Solution:

  1. Ensure OpenAI is instrumented (done automatically by setup_tracing)
  2. Verify tracer is registered before creating assistants:

Issue: Traces showing in wrong project#

Symptom: Traces appear in unexpected project

Solution: Specify project name explicitly:

Debug Logging#

Enable debug logging to troubleshoot tracing issues:

Additional Resources#

Phoenix Resources#

Grafi Resources#

Support#

For issues related to:

  • Graphite tracing integration: Open an issue on the Grafi repository
  • Phoenix: Check the Phoenix GitHub issues or documentation