OpenTelemetry MCP Sunucusu

LLM izlerini AI yardımı ile sorgula ve analiz et. Claude'a pahalı API çağrılarını bulmayı, hataları debug etmeyi, model performansını karşılaştırmayı ya da token kullanımını izlemeyi sor—hepsi IDE'nin içinden.

OpenTelemetry trace backend'lerine (Jaeger, Tempo, Traceloop) bağlanan bir MCP (Model Context Protocol) sunucusu; OpenLLMetry semantic conventions aracılığıyla LLM observability'si için özel destek sunar.

Aksiyon halinde gör:

https://github.com/user-attachments/assets/e2106ef9-0a58-4ba0-8b2b-e114c0b8b4b9

İçindekiler

• Hızlı Başlangıç
• Kurulum
• Özellikler
• Yapılandırma
• Araçlar Referansı
• Örnek Sorgular
• Yaygın İş Akışları
• Sorun Giderme
• Geliştirme
• Destek

Hızlı Başlangıç

Kurulum gerekmez! İstemcinizi sunucuyu doğrudan PyPI'dan çalıştıracak şekilde yapılandır:

// claude_desktop_config.json'a ekle:
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Ya da uvx kullan (alternatif):

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uvx",
      "args": ["opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Hepsi bu kadar! Claude'a sor: "Son bir saatten hatalar içeren izleri göster"

Kurulum

Son Kullanıcılar İçin (Önerilir)

# Kurulum olmadan çalıştır (önerilir)
pipx run opentelemetry-mcp --backend jaeger --url http://localhost:16686

# Veya uvx ile
uvx opentelemetry-mcp --backend jaeger --url http://localhost:16686

Bu yaklaşım:

• ✅ Her zaman en son sürümü kullanır
• ✅ Global kurulum gerekmez
• ✅ İzole ortam otomatik olarak
• ✅ Tüm platformlarda çalışır

İstemci Başına Entegrasyon

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uvx",
      "args": ["opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "traceloop",
        "BACKEND_URL": "https://api.traceloop.com",
        "BACKEND_API_KEY": "your_traceloop_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "/absolute/path/to/opentelemetry-mcp-server/start_locally.sh"
    }
  }
}

{
  "mcpServers": {
    "opentelemetry-mcp-jaeger": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/opentelemetry-mcp-server",
        "run",
        "opentelemetry-mcp"
      ],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

# Sunucunun mevcut olduğunu doğrula
claude-code mcp list

# Claude Code'u OpenTelemetry izlerine erişim ile kullan
claude-code "Show me traces with errors from the last hour"

{
  "opentelemetry-mcp": {
    "command": "pipx",
    "args": ["run", "opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

{
  "opentelemetry-mcp": {
    "command": "uvx",
    "args": ["opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

{
  "opentelemetry-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "/absolute/path/to/opentelemetry-mcp-server",
      "run",
      "opentelemetry-mcp"
    ],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

{
  "opentelemetry-mcp": {
    "command": "pipx",
    "args": ["run", "opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

{
  "opentelemetry-mcp": {
    "command": "uvx",
    "args": ["opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

{
  "opentelemetry-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "/absolute/path/to/opentelemetry-mcp-server",
      "run",
      "opentelemetry-mcp"
    ],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uvx",
      "args": ["opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

gemini "Analyze token usage for gpt-4 requests today"

{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/opentelemetry-mcp-server",
        "run",
        "opentelemetry-mcp"
      ],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Ön koşullar:

• Python 3.11 veya daha yüksek
• pipx veya uv kurulu

# pipx ile kur
pipx install opentelemetry-mcp

# Doğrula
opentelemetry-mcp --help

# Güncelle
pipx upgrade opentelemetry-mcp

pip install opentelemetry-mcp

Özellikler

Temel Yetenekler

• 🔌 Birden Fazla Backend Desteği - Jaeger, Grafana Tempo veya Traceloop'a bağlan
• 🤖 LLM-Odaklı Tasarım - AI uygulaması izlerini analiz etmek için özel araçlar
• 🔍 İleri Filtreleme - Güçlü operatörlere sahip generic filtre sistemi
• 📊 Token Analitikleri - Model ve hizmetler arasında LLM token kullanımını izle ve topla
• ⚡ Hızlı ve Tür-Güvenli - Async Python ve Pydantic doğrulaması ile yapılmıştır

Araçlar

Backend Destek Matrisi

_{* Jaeger, span arama için service_name parametresi gerektirir}

Geliştiriciler İçin

Projeye katkıda bulunuyorsan veya yerel değişiklikler yapmak istiyorsan:

# Repository'i klonla
git clone https://github.com/traceloop/opentelemetry-mcp-server.git
cd opentelemetry-mcp-server

# UV ile bağımlılıkları kur
uv sync

# Veya pip ile development modunda kur
uv pip install -e ".[dev]"

Yapılandırma

Desteklenen Backend'ler

Hızlı Yapılandırma

Seçenek 1: Ortam Değişkenleri (.env dosyası oluştur - bkz. .env.example)

BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

Seçenek 2: CLI Argümanları (ortam değişkenlerini geçersiz kıl)

opentelemetry-mcp --backend jaeger --url http://localhost:16686
opentelemetry-mcp --backend traceloop --url https://api.traceloop.com --api-key YOUR_KEY

Yapılandırma Önceliği: CLI argümanları > Ortam değişkenleri > Varsayılanlar

# Backend yapılandırması
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

# İsteğe bağlı: API anahtarı (esas olarak Traceloop için)
BACKEND_API_KEY=

# İsteğe bağlı: İstek zaman aşımı (varsayılan: 30s)
BACKEND_TIMEOUT=30

# İsteğe bağlı: Logging seviyesi
LOG_LEVEL=INFO

# İsteğe bağlı: Sorgu başına maksimum izler (varsayılan: 100)
MAX_TRACES_PER_QUERY=100

BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

BACKEND_TYPE=tempo
BACKEND_URL=http://localhost:3200

BACKEND_TYPE=traceloop
BACKEND_URL=https://api.traceloop.com
BACKEND_API_KEY=your_api_key_here

Kullanım

start_locally.sh ile Hızlı Başlangıç (Önerilir)

Sunucuyu çalıştırmanın en kolay yolu:

./start_locally.sh

Bu script tüm yapılandırmayı yönetir ve sunucuyu stdio modunda başlatır (Claude Desktop entegrasyonu için mükemmel). Backend'i değiştirmek için, basitçe script'i düzenle ve tercih ettiğin backend'i aç.

Manuel Çalıştırma

İleri kullanım durumları veya özel yapılandırmalar için, sunucuyu manuel olarak çalıştırabilirsin.

stdio Transport (Claude Desktop için)

MCP sunucusunu yerel/Claude Desktop entegrasyonu için stdio transport'u ile başlat:

# pipx/pip ile kurulduysa
opentelemetry-mcp

# Klonlanan repository'den UV ile çalıştırıyorsa
uv run opentelemetry-mcp

# Backend geçersiz kılması ile (pipx/pip)
opentelemetry-mcp --backend jaeger --url http://localhost:16686

# UV ile
uv run opentelemetry-mcp --backend jaeger --url http://localhost:16686

HTTP Transport (Ağ Erişimi için)

MCP sunucusunu uzaktan erişim için HTTP/SSE transport'u ile başlat:

# pipx/pip ile kurulduysa
opentelemetry-mcp --transport http

# Klonlanan repository'den UV ile çalıştırıyorsa
uv run opentelemetry-mcp --transport http

# Özel host ve port belirt (pipx/pip)
opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000

# UV ile
uv run opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000

HTTP sunucusu varsayılan olarak http://localhost:8000/sse adresinde erişilebilir olacak.

Transport Kullanım Durumları:

• stdio transport: Yerel kullanım, Claude Desktop entegrasyonu, tek işlem
• HTTP transport: Uzaktan erişim, birden fazla istemci, ağ dağıtımı, örnek uygulamalar

Araçlar Referansı

1. search_traces

Esnek filtreleme ile izleri ara:

{
  "service_name": "my-app",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "gen_ai_system": "openai",
  "gen_ai_model": "gpt-4",
  "min_duration_ms": 1000,
  "has_error": false,
  "limit": 50
}

Parametreler:

• service_name - Hizmete göre filtrele
• operation_name - İşleme göre filtrele
• start_time / end_time - ISO 8601 zaman damgaları
• min_duration_ms / max_duration_ms - Süre filtreleri
• gen_ai_system - LLM sağlayıcısı (openai, anthropic, vb.)
• gen_ai_model - Model adı (gpt-4, claude-3-opus, vb.)
• has_error - Hata durumuna göre filtrele
• tags - Özel etiket filtreleri
• limit - Maksimum sonuç (1-1000, varsayılan: 100)

Döner: Token sayıları ile iz özeti listesi

2. get_trace

Tüm span'ları ve OpenLLMetry özniteliklerini içeren tam iz detaylarını al:

{
  "trace_id": "abc123def456"
}

Döner: Şunları içeren tam iz ağacı:

• Tüm span'lar ve öznitelikler
• LLM span'ları için ayrıştırılmış OpenLLMetry verileri
• Span başına token kullanımı
• Hata bilgisi

3. get_llm_usage

Toplu token kullanımı metriklerini al:

{
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "service_name": "my-app",
  "gen_ai_system": "openai",
  "limit": 1000
}

Döner: Şunları içeren toplu metrikler:

• Toplam prompt/completion/toplam token'lar
• Modele göre dağılım
• Hizmete göre dağılım
• İstek sayıları

4. list_services

Mevcut tüm hizmetleri listele:

{}

Döner: Hizmet adlarının listesi

5. find_errors

Hata içeren izleri bul:

{
  "start_time": "2024-01-01T00:00:00Z",
  "service_name": "my-app",
  "limit": 50
}

Döner: Şunları içeren hata izleri:

• Hata mesajları ve türleri
• Stack trace'ler (kısaltılmış)
• LLM'ye özel hata bilgisi
• Hata span detayları

Örnek Sorgular

Pahalı OpenAI İşlemlerini Bul

Doğal Dil: "Son bir saatten 5 saniyeden daha uzun süren OpenAI izlerini göster"

Tool Çağrısı: search_traces

{
  "service_name": "my-app",
  "gen_ai_system": "openai",
  "min_duration_ms": 5000,
  "start_time": "2024-01-15T10:00:00Z",
  "limit": 20
}

Yanıt:

{
  "traces": [
    {
      "trace_id": "abc123...",
      "service_name": "my-app",
      "duration_ms": 8250,
      "total_tokens": 4523,
      "gen_ai_system": "openai",
      "gen_ai_model": "gpt-4"
    }
  ],
  "count": 1
}

Model Başına Token Kullanımını Analiz Et

Doğal Dil: "Bugün her model için kaç token kullandık?"

Tool Çağrısı: get_llm_usage

{
  "start_time": "2024-01-15T00:00:00Z",
  "end_time": "2024-01-15T23:59:59Z",
  "service_name": "my-app"
}

Yanıt:

{
  "summary": {
    "total_tokens": 125430,
    "prompt_tokens": 82140,
    "completion_tokens": 43290,
    "request_count": 487
  },
  "by_model": {
    "gpt-4": {
      "total_tokens": 85200,
      "request_count": 156
    },
    "gpt-3.5-turbo": {
      "total_tokens": 40230,
      "request_count": 331
    }
  }
}

Hata İçeren İzleri Bul

Doğal Dil: "Son bir saatten tüm hataları göster"

Tool Çağrısı: find_errors

{
  "start_time": "2024-01-15T14:00:00Z",
  "service_name": "my-app",
  "limit": 10
}

Yanıt:

{
  "errors": [
    {
      "trace_id": "def456...",
      "service_name": "my-app",
      "error_message": "RateLimitError: Too many requests",
      "error_type": "openai.error.RateLimitError",
      "timestamp": "2024-01-15T14:23:15Z"
    }
  ],
  "count": 1
}

Model Performansını Karşılaştır

Doğal Dil: "GPT-4 ve Claude arasında performans farkı nedir?"

Tool Çağrısı 1: gpt-4 için get_llm_model_stats

{
  "model_name": "gpt-4",
  "start_time": "2024-01-15T00:00:00Z"
}

Tool Çağrısı 2: claude-3-opus için get_llm_model_stats

{
  "model_name": "claude-3-opus-20240229",
  "start_time": "2024-01-15T00:00:00Z"
}

Yüksek Token Kullanımını Araştır

Doğal Dil: _"Bugün hangi istekler en