Skip to content

akshayparseja/observability-copilot

BranchesTags

Repository files navigation

Observability Copilot 🚀

Intelligent, AI-powered observability automation for your GitHub repositories

Observability Copilot automatically detects your application's framework, analyzes existing instrumentation (Prometheus metrics and OpenTelemetry traces), and generates pull requests with production-ready observability code. Say goodbye to manual instrumentation—let the copilot handle it for you!

🎯 What It Does

  1. Scans your GitHub repository to detect the framework and programming language
  2. Analyzes existing observability implementations:
    • Prometheus metrics exposition
    • OpenTelemetry tracer initialization & span creation
  3. Generates framework-specific instrumentation code:
    • Adds dependencies to build manifests
    • Creates tracer/metrics initialization code
    • Sets up exporters and configuration
  4. Creates a pull request automatically with all the changes
  5. Manages telemetry modes through an intuitive dashboard

🌟 Key Features

  • ✅ Framework Detection - Automatically identifies Go, Python, Java, Node.js, .NET, and Rust projects
  • ✅ Smart Instrumentation Detection - Two-pass analysis (registration + usage) for accurate detection
  • ✅ Code Generation - Production-ready instrumentation for multiple frameworks
  • ✅ GitHub Integration - Creates PRs with properly formatted commits
  • ✅ Flexible Telemetry Modes - Choose between metrics, traces, both, or none
  • ✅ Database Persistence - Stores scan results and configuration
  • ✅ Web Dashboard - Beautiful React UI for managing repositories and settings
  • ✅ Docker & Kubernetes Ready - Deploy locally or to cloud

📊 Supported Frameworks

Framework Status Metrics Traces Supported Build Files
Go ✅ Full ✅ ✅ go.mod, main.go
Python ✅ Full ✅ ✅ requirements.txt, setup.py
Java ✅ Full ✅ ✅ pom.xml, build.gradle
Node.js 🚧 Planned - - package.json
.NET 🚧 Planned - - *.csproj
Rust 🚧 Planned - - Cargo.toml

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Frontend (React)                        │
│  Dashboard UI with Repository Management & Telemetry Config │
│  (copilot-ui/) - Port 80 (via Nginx)                       │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP/REST
                       ▼
┌─────────────────────────────────────────────────────────────┐
│               Backend API (Go + Gin)                        │
│           cmd/server/main.go - Port 8000                    │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │   Scanner   │  │  Generator   │  │ GitHub PR Bot   │   │
│  │ Framework   │  │ Code Gen for │  │ Commit & Push   │   │
│  │ Detection   │  │ All langs    │  │ Create PR       │   │
│  └─────────────┘  └──────────────┘  └─────────────────┘   │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │          ToggleSpec Manager                          │   │
│  │  (Telemetry Mode Configuration & Persistence)       │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┬────────────┐
        ▼              ▼              ▼            ▼
    ┌────────┐   ┌──────────┐  ┌────────────┐ ┌──────────┐
    │ GitHub │   │PostgreSQL│  │ Git CLI    │ │ Git SSH  │
    │ API    │   │ Database │  │ (clone)    │ │ (auth)   │
    └────────┘   └──────────┘  └────────────┘ └──────────┘

Component Breakdown

Scanner (pkg/scanner/scanner.go)

  • Clones the target repository
  • Detects framework by checking for framework-specific files
  • Performs two-pass instrumentation detection:
    • Pass 1: Looks for registration calls (e.g., prometheus.MustRegister, sdktrace.NewTracerProvider)
    • Pass 2: Searches for actual usage (e.g., http.Handle("/metrics"), tracer.Start())
  • Returns ScanResult with framework, services, and instrumentation status

Generator (pkg/generator/)

  • generator.go - Main dispatcher
  • go_generator.go - Go-specific instrumentation
  • python_generator.go - Python-specific instrumentation
  • java_generator.go - Java-specific instrumentation
  • Generates InstrumentationPlan with file changes:
    • Dependency additions (go.mod, requirements.txt, pom.xml)
    • Tracer initialization code
    • Metrics setup code
    • Configuration files

GitHub Integration (pkg/github/pr.go)

  • Clones repository to temporary directory
  • Creates feature branch (feat/add-prometheus-metrics, feat/add-opentelemetry-traces, etc.)
  • Applies generated code changes
  • Commits with descriptive message
  • Pushes to origin
  • Creates PR via GitHub API

ToggleSpec Manager (pkg/togglespec/)

  • Generates YAML-based telemetry configuration
  • Supports four modes: metrics, traces, both, none
  • Persists configuration to database for future reference

📋 Database Schema

The application uses PostgreSQL with three main tables:

repos - Repository Metadata

CREATE TABLE repos (
  id VARCHAR(255) PRIMARY KEY,           -- Extracted from repo URL
  name VARCHAR(255) NOT NULL,            -- Repository name
  github_url TEXT NOT NULL,              -- Full GitHub URL
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

services - Detected Services/Applications

CREATE TABLE services (
  id VARCHAR(255) PRIMARY KEY,           -- Format: "{repo_id}-{service_name}"
  repo_id VARCHAR(255) NOT NULL,         -- Foreign key to repos
  name VARCHAR(255) NOT NULL,            -- Service name (e.g., "go-service")
  framework VARCHAR(255),                -- Detected framework (Go, Python, Java, etc.)
  has_metrics BOOLEAN DEFAULT FALSE,     -- Prometheus metrics detected
  has_otel BOOLEAN DEFAULT FALSE,        -- OpenTelemetry traces detected
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

togglespecs - Telemetry Configuration per Environment

CREATE TABLE togglespecs (
  id VARCHAR(255) PRIMARY KEY,           -- Format: "{service_id}-{environment}"
  service_id VARCHAR(255) NOT NULL,      -- Foreign key to services
  environment VARCHAR(50) NOT NULL,      -- Environment (dev, staging, prod, etc.)
  telemetry_mode VARCHAR(50) DEFAULT 'both',  -- Current mode: metrics|traces|both|none
  spec TEXT,                             -- YAML configuration
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

🔌 REST API Endpoints

Health & Status

GET /api/v1/health
# Response: { "status": "ok" }

Repository Management

# List all imported repositories
GET /api/v1/repos
# Response: [{ id, name, github_url }, ...]

# Scan a repository and store results
POST /api/v1/imports
# Body: { "github_url": "https://github.com/user/repo.git", "telemetry_mode": "both" }
# Response: { "message": "Scan complete", "repo_id": "...", "result": {...} }

# Get instrumentation plan for repository
GET /api/v1/repos/:repo_id/plan
# Response: { "repo_id": "...", "services": [...], "github_url": "..." }

Telemetry Configuration

# Get telemetry config for a service in an environment
GET /api/v1/repos/:repo_id/services/:svc/toggles/:env
# Response: { "spec": "...", "telemetry_mode": "both" }

# Update telemetry mode
PUT /api/v1/repos/:repo_id/services/:svc/toggles/:env
# Body: { "telemetry_mode": "metrics" }
# Response: { "message": "ToggleSpec saved" }

Pull Request Creation

# Create instrumentation PR for repository
POST /api/v1/repos/:repo_id/create-pr
# Body: { "telemetry_mode": "both" }
# Response: { "pr_url": "https://github.com/user/repo/pull/123", "message": "..." }

🎮 Telemetry Modes

The platform supports four flexible telemetry modes:

Mode Metrics Traces Use Case
metrics ✅ ❌ Cost-conscious, basic monitoring
traces ❌ ✅ Debugging, performance analysis, error tracking
both ✅ ✅ Complete observability (recommended)

Smart Mode Selection

The UI automatically determines available modes based on existing instrumentation:

No metrics + No traces → All modes available (suggest "both")
Has metrics + No traces → Only "traces" and "none" available
No metrics + Has traces → Only "metrics" and "none" available
Has metrics + Has traces → Only "none" available

This prevents duplicate instrumentation and keeps code clean.

🚀 Getting Started

Prerequisites

  • Docker & Docker Compose (recommended for local dev)
  • Git (for cloning repositories)
  • PostgreSQL 13+ (or use Docker)
  • Go 1.21+ (for backend development only)
  • Node.js 18+ (for frontend development only)
  • GitHub Token (for PR creation) - Get one here

Option 1: Local Development (Backend + Frontend Separately)

1. Start PostgreSQL

docker run -d \
  --name observability-copilot-db \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=copilot \
  -p 5432:5432 \
  postgres:13

2. Run Backend Server

cd backend

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"  # Your GitHub token
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/copilot?sslmode=disable"
export PORT=8000

go mod download
go mod tidy
go run ./cmd/server/main.go

Backend will start on http://localhost:8000

3. Run Frontend

cd copilot-ui

npm install
npm start

Frontend will start on http://localhost:3000 with automatic proxy to backend

Option 2: Kubernetes Deployment

1. Create namespace

kubectl apply -f k8s/namespaces/observability-ns.yaml

2. Create ConfigMap for backend

kubectl create configmap backend-config \
  -n observability-copilot \
  --from-literal=DATABASE_URL="postgres://postgres:postgres@postgres:5432/copilot?sslmode=disable"

3. Deploy database

# Helm (recommended)
helm install postgres bitnami/postgresql \
  -n observability-copilot \
  --set auth.password=postgres

# Or using manifests
bash backend/k8s/db/startup.sh

4. Build and push images

# Backend
docker build -t your-registry/observability-copilot-backend:latest ./backend
docker push your-registry/observability-copilot-backend:latest

# Frontend
cd copilot-ui && npm run build && cd ..
docker build -t your-registry/observability-copilot-frontend:latest ./copilot-ui
docker push your-registry/observability-copilot-frontend:latest

5. Deploy services

# Update image references in k8s manifests
kubectl apply -f backend/k8s/backend/deployment.yaml
kubectl apply -f backend/k8s/backend/service.yaml
kubectl apply -f k8s/ingress.yaml

6. Access the dashboard

kubectl port-forward svc/frontend 3000:80 -n observability-copilot
# Then visit http://localhost:3000

📖 How It Works - Step by Step

1. Scan a Repository

User enters GitHub URL in the dashboard (e.g., https://github.com/user/my-go-app.git)

User Input → POST /api/v1/imports → Scanner → Database

The scanner:

  1. Creates temp dir in /tmp/{repo_id}
  2. Runs: git clone --depth=1 <url> <path> (shallow clone for speed)
  3. Detects framework by checking for files:
    • Go: go.mod
    • Python: requirements.txt, setup.py, pyproject.toml, Pipfile
    • Java: pom.xml, build.gradle
    • etc.
  4. Uses grep -r -i to search for instrumentation patterns:
    • Metrics patterns: prometheus.MustRegister, http.Handle("/metrics"), etc.
    • Trace patterns: tracer.Start, sdktrace.NewTracerProvider, OTLPSpanExporter, etc.
  5. Returns ScanResult with framework and instrumentation status
  6. Stores repo and services in database

2. Review Results & Select Mode

Frontend displays scan results with smart mode recommendations:

Framework: Go
Has Metrics: ❌ No
Has Traces: ❌ No

Suggested Mode: "both" ✨

Available Options:
  ○ Metrics (Prometheus)
  ○ Traces (OpenTelemetry)
  ● Both (Hybrid) ← Default
  ○ None

User can override the suggestion if needed.

3. Generate & Create PR

User clicks "Create Pull Request" button

Selection → POST /api/v1/repos/:id/create-pr → Generator → GitHub

The backend:

  1. Fetches repo info and existing instrumentation status
  2. Calls Generate(framework, service, mode) to create plan
  3. Calls CreateInstrumentationPR(url, plan, hasMetrics, hasOtel) which:
    • Clones repo to temp dir
    • Creates feature branch: feat/add-prometheus-metrics or feat/add-opentelemetry-traces
    • For each file in plan:
      • If action: "append" → add content to end of file
      • If action: "modify" → find line anchor and insert after
    • Git commits: "chore: add observability instrumentation"
    • Git pushes to origin
    • Creates PR via GitHub API with description of changes
  4. Returns PR URL to frontend

User sees: "✅ PR created! Open PR" and can click to review

4. Manage Configuration

Once repository is scanned, user can:

  • View current telemetry mode in dashboard
  • Switch between available modes (respecting smart detection)
  • Update environment-specific settings
  • View generated ToggleSpec YAML

All changes are persisted to the database.

GitHub Token Management

  • Store GITHUB_TOKEN as a secret (never commit)
  • Set as environment variable before starting backend
  • Token requires repo scope (read/write) for PR creation
  • Consider using GitHub App for production deployments

Repository Cloning

Current implementation:

  • Uses shallow clone (--depth=1) for speed
  • Clones to /tmp/{repo_id} (world-readable by default)
  • Removes cloned directory after processing

Security notes:

  • Only clones public repositories (requires token for private repos)
  • No validation of repository source (use GITHUB_TOKEN with limited org access)
  • Consider adding repository URL whitelist in production
  • Add timeout to clone operation to prevent hanging on large repos

Database

  • PostgreSQL credentials should be in environment variables
  • Use strong passwords in production
  • Consider enabling SSL for database connections
  • Regularly backup the database

API

  • All endpoints require CORS headers (enabled in backend)
  • No authentication currently implemented (add before production use)
  • Rate limit GitHub API calls in production

🛠️ Development

Building Images

Backend:

cd backend
docker build -t observability-copilot-backend:latest .

Frontend:

cd copilot-ui
npm run build
docker build -t observability-copilot-frontend:latest .

Key Dependencies

Backend (Go 1.21)

  • github.com/gin-gonic/gin - HTTP framework
  • github.com/lib/pq - PostgreSQL driver

Frontend (React 19 + TypeScript)

  • @mui/material - UI component library
  • axios - HTTP client
  • react-scripts - Build tooling

📚 API Usage Examples

1. Scan a Repository

curl -X POST http://localhost:8000/api/v1/imports \
  -H "Content-Type: application/json" \
  -d '{
    "github_url": "https://github.com/kubernetes/kubernetes.git",
    "telemetry_mode": "both"
  }'

Response:

{
  "message": "Scan complete",
  "repo_id": "kubernetes",
  "result": {
    "framework": "Go",
    "services": ["kubernetes-service"],
    "has_metrics": true,
    "has_otel": false
  }
}

2. Get Instrumentation Plan

curl http://localhost:8000/api/v1/repos/kubernetes/plan

3. Create Pull Request

curl -X POST http://localhost:8000/api/v1/repos/kubernetes/create-pr \
  -H "Content-Type: application/json" \
  -d '{ "telemetry_mode": "both" }'

Response:

{
  "pr_url": "https://github.com/kubernetes/kubernetes/pull/120456",
  "message": "Pull request created successfully"
}

4. Get/Update Telemetry Config

# Get current config
curl http://localhost:8000/api/v1/repos/kubernetes/services/kubernetes-service/toggles/dev

# Update config
curl -X PUT http://localhost:8000/api/v1/repos/kubernetes/services/kubernetes-service/toggles/dev \
  -H "Content-Type: application/json" \
  -d '{ "telemetry_mode": "metrics" }'

📋 Roadmap

Phase 1 (Current)

  • ✅ Go, Python, Java support
  • ✅ Metrics & Traces detection
  • ✅ PR creation automation
  • ✅ React dashboard
  • ✅ ToggleSpec configuration

Phase 2 (In Progress)

  • 🚧 Node.js instrumentation
  • 🚧 .NET instrumentation
  • 🚧 Rust instrumentation

Phase 3 ( To be Planned)

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for detailed guidelines on: See CONTRIBUTING.md for detailed contribution guidelines and areas.

📄 License

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

More info: MIT License on OpenSource.org

💬 Support

  • 📧 Issues - Open an issue on GitHub for bugs and feature requests
  • 📖 Documentation - Check docs/OBSERVABILITY_SETUP.md for detailed observability stack information
  • 💡 Ideas - Discussions welcome in GitHub Discussions

📞 Quick Links

Made with ❤️ by the Observability Copilot Team

Automating observability, one repository at a time.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages