phoenix

Phoenix Platform

Phoenix is an observability cost optimization platform that reduces metrics cardinality by up to 70% while maintaining critical visibility. Using intelligent pipeline optimization and agent-based architecture, Phoenix helps organizations cut observability costs without sacrificing insights.

🚀 Quick Start

# Clone the repository
git clone https://github.com/phoenix/platform.git
cd platform

# Run the setup script for single-VM deployment
./deployments/single-vm/scripts/setup-single-vm.sh

# Start Phoenix with Docker Compose
cd deployments/single-vm
docker-compose up -d

# Access the dashboard
open http://localhost:3000

# Install agents on target hosts
curl -sSL http://localhost:8080/install-agent.sh | sudo bash

See QUICKSTART.md for detailed setup instructions.

📋 Key Features

• 70% Cost Reduction - Intelligent metrics filtering reduces cardinality without losing critical data
• Real-time Monitoring - WebSocket-based live updates for experiments and metrics
• Agent-Based Architecture - Distributed agents with task polling and heartbeat monitoring
• A/B Testing Framework - Safe rollout with baseline vs candidate pipeline comparison
• Pipeline Templates - Pre-built optimization strategies (Adaptive Filter, TopK, Hybrid)
• Dual Collector Support - Choose between OpenTelemetry or NRDOT (New Relic Distribution)
• NRDOT Integration - Advanced cardinality reduction with New Relic's optimized collectors
• Enterprise Ready - PostgreSQL storage, TLS support, comprehensive monitoring

🏗️ Architecture Overview

Phoenix uses a modular monorepo structure with agent-based architecture:

┌─────────────────┐         ┌─────────────────┐
│   Phoenix API   │◄────────┤   Dashboard     │
│  (Port 8080)    │         │   (React 18)    │
│  REST + WS      │         └─────────────────┘
└────────┬────────┘
         │ Task Queue (PostgreSQL)
         │ Long-polling (30s timeout)
    ┌────▼────┐
    │ Phoenix │────► OTel/NRDOT ────► Observability
    │ Agents  │      Collector       │ Backends
    └─────────┘                      └─────────────

Core Components

• Phoenix API - Central control plane with REST/WebSocket APIs
• Phoenix Agent - Distributed agents deploying pipeline configurations
• Phoenix CLI - Command-line interface for operations
• Dashboard - React-based UI for monitoring and management

📚 Documentation

Getting Started

• Quick Start Guide - Get running in 5 minutes
• Concepts & Terminology - Core concepts
• First Experiment - Create your first cost optimization

Architecture & Design

• System Architecture - High-level design
• Platform Architecture - Detailed platform architecture
• Messaging Decision - Messaging architecture decisions
• Main Architecture - Core architecture overview

API Reference

• REST API - HTTP endpoints reference
• WebSocket API - Real-time updates
• Phoenix API v2 - Comprehensive API documentation
• Pipeline Validation - Pipeline validation API

User Guides

• Getting Started - Core concepts
• First Experiment - Create your first experiment
• UX Design - UI/UX documentation
• Load Simulation - Load testing profiles

Developer Resources

• Development Setup - Local environment setup
• Project Structure - Codebase organization
• Testing Guide - Test strategies and execution
• Contributing - Contribution guidelines

Operations

• Single-VM Deployment - Production-ready single VM setup
• Docker Compose Guide - Container orchestration
• Configuration Reference - All config options
• Production Guide - Production deployment
• NRDOT Integration - New Relic collector setup
• Scaling & Performance - Scaling strategies
• Troubleshooting - Troubleshooting guide

Tutorials

• First Experiment - Step-by-step guide
• NRDOT Integration - New Relic integration
• Docker Compose Setup - Container deployment

🔌 Collector Support

Phoenix supports multiple telemetry collectors:

OpenTelemetry Collector (Default)

• Industry-standard collector with wide ecosystem support
• Configurable processors for basic cardinality reduction
• Compatible with any OTLP-compliant backend

NRDOT (New Relic Distribution of OpenTelemetry)

• Advanced cardinality reduction with New Relic's algorithms
• Up to 80% reduction in metric volume
• Automatic preservation of critical metrics
• Native integration with New Relic platform

Quick Start with NRDOT:

# Using environment variables
export USE_NRDOT=true
export NEW_RELIC_LICENSE_KEY=your-license-key

# Or using CLI
phoenix-cli experiment create \
  --name "NRDOT Test" \
  --use-nrdot \
  --nr-license-key $NEW_RELIC_LICENSE_KEY \
  --candidate-pipeline nrdot-cardinality

See NRDOT Integration Guide for detailed setup.

🛠️ Development

Prerequisites

• Go 1.21+
• Node.js 18+
• Docker & Docker Compose
• PostgreSQL 15+ (primary database)

Build from Source

# Install dependencies
make setup

# Build all components
make build

# Run tests
make test

# Start development environment
make dev-up

See Development Guide for detailed instructions.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Good First Issues

• Check out issues labeled good first issue
• Join our Discord community for help

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔗 Links

• Documentation
• Issue Tracker
• Discord Community
• Blog