Kendi Sunucunuzda Langfuse Kurulumu ve Yapılandırması

Neden bir yapay zeka aracısını izlemelisiniz

Langfuse uygulamasını kendi sunucunuzda barındırmanızın amacı, aracınızın bir çalışma sırasında gerçekte ne yaptığını görmektir. Langfuse, açık kaynaklı bir LLM (büyük dil modeli) gözlemlenebilirlik aracıdır. Her istemi, her model yanıtını, her araç çağrısını ve her token değerini kaydeder; ardından bunları açıp inceleyebileceğiniz tek bir izleme (trace) altında gruplandırır. Aracı kendi VPS sunucunuzda çalıştırmak, bu istemlerin kontrolünüz altındaki sunucudan asla dışarı çıkmamasını sağlar.

Bununla uğraşmanın nedeni açıktır. Göremediğiniz bir maliyet veya kalite sorununu çözemezsiniz. Bir sağlayıcı faturası size Salı gününün maliyetinin Pazartesi gününün dört katı olduğunu söyler. Bir izleme kaydı ise size hangi aracı çalıştırmasının buna neden olduğunu, hangi istemin 40.000 token değerine ulaştığını ve hangi yeniden deneme döngüsünün pes etmeden önce dokuz kez çalıştığını gösterir. Fatura size sadece sayıyı verir. İzleme kaydı ise bu sayıyı üreten kodu sunar.

Bu kılavuz boyunca üç terim kullanılmaktadır. Trace (izleme), aracınızın uçtan uca tek bir çalışma sürecidir. Observation (gözlem), bu süreç içindeki tek bir adımdır: sıradan kodlar için bir span, modele yapılan çağrılar için bir generation. Score (puan), bir insan incelemesi veya otomatik bir değerlendirici tarafından bir izleme kaydına atanan değerdir. Langfuse, dağıtık izleme için satıcıdan bağımsız standart olan OpenTelemetry (OTel) protokolünü destekler; bu sayede halihazırda sahip olduğunuz enstrümantasyon araçlarını Langfuse'a yönlendirebilirsiniz.

Langfuse self-hosting mimarisi

Langfuse v4 tek bir container değildir. İki uygulama container'ı ve dört depolama servisinden oluşur; tek bir VPS üzerinde bu altı bileşenin tamamı çalışır.

• langfuse-web web arayüzünü ve ingestion API'sini sunar.
• langfuse-worker arka planda kuyruğu boşaltır. Ingestion yığınlarını ayrıştırır, maliyet hesaplamalarını yapar ve gece çalışan veri saklama (retention) görevini yürütür.
• Postgres; kullanıcılar, organizasyonlar, projeler, API anahtarları ve istemler (prompts) gibi işlemsel verileri tutar.
• ClickHouse; gözlemler ve puanlar dahil olmak üzere izleme (trace) verilerini tutar. Analitik sorgular için tasarlanmış bir sütun tabanlı veritabanıdır; yüz milyonlarca satırlık bir dashboard'un hızlı yanıt vermesinin nedeni budur.
• Redis; web ve worker arasında yer alan kuyruk ve önbellek mekanizmasıdır.
• MinIO; sunucu üzerinde S3 uyumlu nesne depolama sağlar. Gelen tüm ham olayları ve eklediğiniz tüm medyaları saklar.

Langfuse, işi yapan üç ana bileşen için minimum kaynak gereksinimlerini yayınlar.

[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

Yalnızca ClickHouse 8 GiB bellek talep eder. Web container'ı ve worker ise 4 GiB bellek ister. Bunlar, Langfuse'un boyutlandırdığı 3 bileşen için yayınlanan alt sınırlardır; Postgres, Redis ve MinIO için ek bellek gereklidir. Projenin kendi Docker Compose kılavuzu, bu hesaplamalarla uyumlu olacak şekilde 4 çekirdekli, 16 GiB bellekli ve yaklaşık 100 GiB depolama alanına sahip bir makine önermektedir.

Bunu 2 GiB belleğe sahip bir planda denemeyin. ClickHouse başlar, bir süre yazma işlemlerini kabul eder ancak arka planda bir birleştirme (merge) işlemi sırasında çöker; çünkü birleştirme işlemi tablonun büyük bir kısmını belleğe yükler. Bu durumda docker compose ps, clickhouse container'ını restarting olarak raporlar, dmesg üzerinde Out of memory: Killed process 1234 (clickhouse-serv) gibi bir satır görülür ve tüm Langfuse dashboard'ları 500 hatası döndürür. Daha düşük yük altında ise ClickHouse sorguyu reddeder ve DB::Exception: Memory limit (total) exceeded hatasını günlüğe kaydeder. Günde birkaç bin izleme gönderen tek bir geliştirici için 8 GiB bellek çalışabilir durumdadır. Planlanması gereken değer ise 16 GiB'dir.

Docker Compose ile Langfuse kurulumu

Depoyu klonlayın. Yığın, bağlantılar ve varsayılan ortam değişkenlerinin tamamı docker-compose.yml içerisinde yer alır.

git clone https://github.com/langfuse/langfuse.git
cd langfuse

Değiştirmeniz gereken her değer ilgili dosyada # CHANGEME ile işaretlenmiştir. Öncelikle üç uygulama gizli anahtarını oluşturun.

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

ENCRYPTION_KEY, 64 onaltılık karakter olarak yazılmış 256 bitlik bir değer olmalıdır; openssl rand -hex 32 komutu tam olarak bunu üretir. Bu değer, örnek üzerinde sakladığınız LLM sağlayıcı anahtarları dahil olmak üzere hassas verileri diskte şifreli tutar. Veri oluştuktan sonra bu değeri değiştirmek, mevcut satırların şifresinin çözülememesine neden olur; bu nedenle ilk kurulumdan itibaren kalıcı olarak kabul edilmelidir. SALT, Langfuse API anahtarlarınızı özetlemek (hash) için kullanılır; bu yüzden değiştirilmesi, ajanlarınızın halihazırda kullandığı tüm anahtarları geçersiz kılar.

Ardından POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH ve MINIO_ROOT_PASSWORD değerlerini ayarlayın. MinIO parolası dört farklı yerde geçer: bir kez MINIO_ROOT_PASSWORD olarak, ardından LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY ve LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY içerisinde. Birini atlamanız durumunda MinIO, istemciyi SignatureDoesNotMatch hatasıyla reddeder; bu hata worker günlüğüne düşerken web arayüzü sağlıklı görünmeye devam eder. Bu değerleri takip edilen compose dosyası yerine bir env dosyasında tutmak, Docker Compose env dosyaları ve gizli anahtarlar bölümünde ele alınan yöntemdir.

Başlamadan önce imaj etiketlerini sabitleyin

Dağıtılan dosya langfuse/langfuse:4 ve langfuse/langfuse-worker:4 etiketlerini kullanır. Bu etiketler zamanla değişir. Langfuse, Postgres ve ClickHouse geçişlerini (migration) başlangıçta otomatik olarak çalıştırır; bu nedenle aylar sonra yapılacak rutin bir docker compose pull işlemi, o sabah yedeklemediğiniz bir veritabanında plansız bir şema değişikliğine yol açar. Her ikisini de bir docker-compose.override.yml içerisinde belirli bir sürüme sabitleyin; Compose bu dosyayı dağıtılan dosyanın üzerine birleştirir, böylece sonraki bir git pull işlemi düzenlemelerinizle çakışmaz.

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.3.1
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.3.1

Ağustos 2026 itibarıyla 4.3.1 sürümü, güncel 4.3 sürümüydü (4.4.0 sürümü o tarihten sonra yayınlanmıştır). Projenin GitHub sürümler sayfasını kontrol edin, kurulum yaptığınız gün güncel olan sürümü sabitleyin ve bu numarayı bilinçli bir şekilde güncelleyin. Dağıtılan dosyadaki depolama imajları halihazırda ana sürümlere, yani postgres:17, clickhouse-server:25.12 ve redis:7 değerlerine sabitlenmiştir ve aynı muameleyi hak ederler.

Sistemi ayağa kaldırın.

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

İlk açılış geçişleri çalıştırır, bu yüzden herhangi bir yanıt almadan önce bir veya iki dakika bekleyin. docker compose ps komutu, running durumunda altı servis listelemelidir. Eğer worker döngüsel olarak yeniden başlıyorsa, nedeni günlüğünde gizlidir: CLICKHOUSE_MIGRATION_URL, 8123 numaralı HTTP portunu değil, 9000 numaralı porttaki ClickHouse yerel protokolünü kullanır; bu değeri 8123'e yönlendirmek hata verirken web container'ı sağlıklı görünmeye devam edebilir.

Sağlık durumunu sunucunun kendisinden kontrol edin.

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

Basit bir /api/public/health çağrısı yalnızca API sürecinin canlı olduğunu kanıtlar, çünkü veritabanını kasıtlı olarak atlar; böylece Postgres kesintilerinde servis hizmet vermeye devam eder. failIfDatabaseUnavailable=true formu, bir izleme aracına tanımlanması gereken formdur ve veritabanı erişilemez olduğunda 503 döner. /api/public/ready ise geçişler tamamlandığında ve container trafiği kabul etmeye hazır olduğunda 200 döner. Her ikisi de standart HTTP kontrolleridir; bu nedenle bir Uptime Kuma durum sayfası bunları izleyebilir ve yığının kapandığını ajanlarınızdan önce size bildirebilir.

TLS katmanını öne alın ve ek portları kapatın

Dağıtılan compose dosyası, web container'ı için 3000:3000 ve MinIO için 9090:9000 portlarını dışarıya açar. Her ikisi de tüm arayüzlere bağlanır. Genel bir IP adresinde bu, 3000 numaralı portu tarayan herkesin kayıt sayfanıza ulaşabileceği ve 9090 numaralı portu tarayan herkesin ham istemlerinizi tutan bucket ile iletişim kurabileceği anlamına gelir.

Yalnızca bir güvenlik duvarı kuralı bunları kapatmaya yetmez. Docker, kendi DNAT kurallarını nat tablosuna yazar ve bu kurallar, ufw'nin filtre kuralları paketi görmeden önce değerlendirilir; bu nedenle ufw deny 3000, yayınlanan portu açık bırakır. Bu durum o kadar çok kişinin karşılaştığı bir sorundur ki, kendi rehberine sahiptir: Docker yayınlanan portları neden ufw'yi atlar. Bunun yerine override dosyanızda loopback adresine bağlayın.

services:
  langfuse-web:
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports:
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

NEXTAUTH_URL, şema dahil olmak üzere tam genel adres olmalıdır; çünkü giriş akışı, callback URL'sini bu değerden oluşturur. Bir HTTPS proxy'sinin arkasında http://localhost:3000 olarak bırakırsanız, oturum açma gidiş-dönüşü tarayıcıyı ulaşamayacağı bir yere yönlendirir.

Şimdi bir reverse proxy'yi 127.0.0.1:3000 adresine yönlendirin ve sertifikayı onun tutmasını sağlayın. Aynı Compose projesindeki Traefik yaygın bir tercihtir ve yönlendirme etiketleri birden fazla uygulamayı bir Traefik reverse proxy arkasında çalıştırma bölümünde ele alınanlarla aynıdır. Eğer sunucuda sadece Langfuse varsa, Caddy aynı işi iki satırda yapar. curl -sI https://langfuse.example.com/api/public/ready ile doğrulayın, ardından ikinci bir makineden curl http://YOUR_IP:3000 adresinin zaman aşımına uğradığını teyit edin.

MinIO ile ilgili bir uyarı: Langfuse, ekli medyayı tarayıcınıza o S3 uç noktasına işaret eden önceden imzalanmış (presigned) URL'ler aracılığıyla sunar. Bu nedenle, resim veya ses içeren çok modlu izler (multi-modal traces) kullanıyorsanız, yalnızca loopback'e bağlı bir MinIO bu eklerin yüklenmemesine neden olur. Proxy'lemeden önce blob depolama yapılandırma sayfasını okuyun, çünkü önceden imzalanmış URL'ye yazılan uç noktanın yayınladığınız adresle eşleşmesi gerekir. Düz metin izleri bu durumdan etkilenmez.

İlk ziyarette hesabınızı oluşturun ve ardından örneği kendinize özel tutun. LANGFUSE_ALLOWED_ORGANIZATION_CREATORS değerini kendi e-posta adresinize ayarlayın; böylece sayfaya ulaşan bir yabancı sunucunuzda bir organizasyon oluşturamaz. Eğer halihazırda kendi kimlik sağlayıcınız olarak Authentik kullanıyorsanız, Langfuse standart bir OIDC bağlantısını kabul eder; böylece hesaplar sadece bu sunucunun bildiği bir parola listesinde yaşamak yerine, diğer uygulamalarınızla birlikte yönetilir.

İlk izlemenizi gönderin

Web arayüzünde bir proje oluşturun ve proje ayarlarından genel (public) ve gizli (secret) anahtarlarınızı kopyalayın. Python SDK, üç ortam değişkenini okur.

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URL, Mart 2026'da yayınlanan SDK v4 sürümündeki değişken adıdır. Daha eski kodlar ve kılavuzlar LANGFUSE_HOST kullanır. İzlemeleriniz kendi sunucunuz yerine Langfuse Cloud'a ulaşıyorsa, bunun nedeni ayarlanmamış bir temel URL'dir; çünkü varsayılan değer barındırılan (hosted) örneği işaret eder.

pip install langfuse opentelemetry-instrumentation-anthropic anthropic

import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

@observe dekoratörü, fonksiyon etrafında bir gözlem (observation) başlatır, argümanlarını ve dönüş değerini yakalar ve bunu halihazırda aktif olan gözlemin altına yerleştirir. AnthropicInstrumentor, Anthropic istemcisi için OpenTelemetry enstrümantasyonudur ve her messages.create çağrısını; model adı, token kullanımı ve gecikme süresini içeren bir nesil (generation) verisine dönüştürür; çağrı noktasında herhangi bir değişiklik yapılması gerekmez.

İki çağrı, kontrol işlemini sizin yerinize yapar. langfuse.auth_check(), hatalı anahtarlar veya yanlış bir temel URL durumunda False döner; bu, kontrol panelinin neden boş olduğunu sorgulamaktan daha hızlıdır. langfuse.flush(), kuyruğa alınan span'ler gönderilene kadar bekler. Kısa ömürlü süreçlerin buna ihtiyacı vardır, çünkü SDK arka planda toplu işlem (batch) yapar ve hemen sonlanan bir betik, gönderilmemiş toplu veriyi de beraberinde götürür.

ClickHouse neden sürekli büyüyor?

İzleme verileri (traces), çoğu kullanıcının kendi sunucusunda barındırdığı en hızlı büyüyen veri türüdür. Her aracı (agent) çalışması, adım başına bir satır yazar ve girdi/çıktı verileri tam olarak saklanır; bu nedenle uzun istemlere sahip yoğun bir aracı, izlediği uygulamadan çok daha fazla bayt üretir. Müdahale edilmediğinde ClickHouse diski doldurur ve disk dolduğunda veri alımı yavaşlamak yerine tamamen durur.

Burada birbirinden bağımsız büyüyen iki unsur vardır ve her biri için ayrı çözüm gerekir.

Birincisi kendi izleme verilerinizdir; bunun çözümü bekletme (retention) ayarıdır. Web arayüzünden proje ayarlarına gidin ve gün cinsinden bir veri bekletme süresi belirleyin. Langfuse en az 3 günlük bir süre kabul eder. Gece çalışan bir iş (job), bu pencerenin dışında kalan izleme verilerini, gözlemleri, puanları ve medya varlıklarını seçerek hem ClickHouse'dan hem de blob depolama alanından siler. Bu işin, varsayılan compose dosyasındaki MinIO root kimlik bilgileriyle zaten sahip olduğu DeleteObject iznine ihtiyacı vardır. Silme işlemi kalıcıdır; bu nedenle uzun vadeli geçmişe ihtiyacınız varsa önce bir blob depolama dışa aktarma işlemi yapılandırın. Langfuse'un kendi tabloları üzerinde manuel olarak TTL ifadeleri yazmayın: ClickHouse ile depolama alanını uyumlu tutan şey bekletme işidir; manuel bir TTL yalnızca bir tarafı siler.

Süreyi gerçek kullanımınıza göre seçin. Maliyet ve kalite incelemeleri aylar öncesine ait verilerle değil, birkaç günlük verilerle yapılır. Küçük bir ekip için 30 gün makul bir başlangıçtır; eğer izleme verilerini yalnızca bir sorun oluştuğunda açıyorsanız 14 gün yeterlidir.

İkincisi ise ClickHouse'un kendi sistem günlük tablolarıdır. Bekletme ayarı yapılandırıldıktan sonra disk büyümeye devam ettiği için bu durum kullanıcıları şaşırtır. ClickHouse kendi tanılamaları için trace_log, text_log, opentelemetry_span_log, metric_log ve asynchronous_metric_log tablolarına veri yazar; bunlar varsayılan olarak TTL içermez ve Langfuse tarafından asla okunmaz. Öncelikle disk alanının nereye gittiğini tespit edin.

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

Bunu docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD" ile çalıştırın. Eğer sistem tabloları listenin başındaysa, bunları bir yapılandırma katmanı (config overlay) ile devre dışı bırakın; çünkü ClickHouse başlangıçta /etc/clickhouse-server/config.d/ içindeki her dosyayı ana yapılandırmasıyla birleştirir.

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
</clickhouse>

Bunu mount edin ve ClickHouse'u yeniden başlatın.

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

Bu işlem yeni yazma işlemlerini durdurur. Diskteki mevcut satırlar orada kalmaya devam eder; bu nedenle DROP TABLE IF EXISTS system.trace_log komutuyla ve kaldırdığınız her tablo için aynı işlemi yaparak alanı geri kazanın. Tanılama verilerini tutmak isterseniz, remove="1" yerine her tablo için agresif bir TTL belirlemek bir alternatiftir; bu konu Langfuse ölçeklendirme belgelerinde detaylandırılmıştır.

Bilmeniz gereken bir tablo daha vardır. blob_storage_file_log, depolama alanınıza yüklenen olay dosyalarını takip eder. Eğer depolama alanınızda bir yaşam döngüsü politikası belirlediyseniz, bu tabloya da uyumlu bir TTL verin; böylece ikisi birbirinden kopmaz.

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

Ayrıca veri diski üzerinde basit bir df -h uyarısı oluşturun. İzleme verileri düzenli bir şekilde büyümez. Yeni bir aracı yayına aldığınız gün büyürler ve bunun ilk belirtisi veri alımının başarısız olması olmamalıdır.

Postgres ve ClickHouse yedekleme

Bir Langfuse yedeği üç bölümden oluşur. Postgres kullanıcılarınızı, organizasyonlarınızı, projelerinizi ve API anahtarlarınızı tutar. ClickHouse izleri (traces) tutar. MinIO ise ham olayları (raw events) saklar. Yalnızca Postgres'i geri yüklerseniz geçmişi olmayan çalışan bir giriş ekranı elde edersiniz. Yalnızca ClickHouse'u geri yüklerseniz, kimsenin giriş yapıp görüntüleyemeyeceği bir geçmişe sahip olursunuz.

Postgres, Langfuse yedekleme belgelerinin önerdiği yöntem olan standart bir pg_dump kullanır.

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

ClickHouse daha fazla dikkat gerektirir; çünkü birleştirme (merge) işlemleri devam ederken kopyalanan canlı bir veri dizini tutarlı bir yedek oluşturmaz. Tek bir sunucu üzerindeki basit yaklaşım, container'ı durdurmak ve volume'u arşivlemektir.

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

YAML dosyasında yazanı değil, docker volume ls komutunun çıktı verdiği volume adını kullanın. Dosya langfuse_clickhouse_data değerini belirtir ancak Compose buna proje adını ön ek olarak ekler; bu nedenle langfuse adlı bir dizindeki klon, langfuse_langfuse_clickhouse_data sonucunu üretir. Bunu yanlış yaparsanız docker run hiçbir uyarı vermeden yeni ve boş bir volume oluşturur, arşiviniz de boş kalır.

Web container'ı, worker işlemeden önce gelen her olayı bucket'a yazar; bu nedenle ClickHouse'un kısa süreli durdurulması, worker'ın sonrasında tekrar deneme yapması anlamına gelir. Bu işlemi trafiğin az olduğu bir saatte yapın ve süreyi kısa tutun. Daha yoğun bir instance için ClickHouse'un kendi BACKUP DATABASE default TO S3(...) ifadesi, sunucuyu durdurmadan tutarlı bir yedek oluşturur. MinIO üçüncü parçadır ve mc mirror veya MinIO'nun sunucu dışındaki bir bucket'a replikasyonu bu ihtiyacı karşılar. Ne üretirseniz üretin, veriyi sunucudan dışarı çıkarın; VPS üzerinde şifreli restic yedekleri bunun içindir.

Redis'in yedeklenmesine gerek yoktur. Kuyruğu ve önbelleği tutar; bu nedenle Redis'in kaybedilmesi yalnızca o an işlenmekte olan olayların kaybına neden olur, daha eski veriler etkilenmez.

Tutarlılık uyarısı gerçektir ve açıkça belirtilmelidir. Postgres ve ClickHouse farklı zamanlarda döküldüğü için, geri yükleme işlemi bir proje satırını izsiz bırakabilir veya artık var olmayan bir projeye ait izler oluşturabilir. Langfuse bunu tolere eder, ancak her iki dökümü de birbirine yakın zamanlarda ve düşük trafikli bir pencerede alın. Olay bucket'ı gerçek güvenlik ağıdır; çünkü Langfuse her gelen olayı işlemeden önce orada kalıcı hale getirir.

En az bir kez boş bir stack üzerine geri yükleme denemesi yapın. Bir kesinti anında değil, şimdi yanlış volume adını tespit etmenin yolu budur.

İlk olarak nelere bakılmalı

İlk hafta içerisinde dört husus öncelik kazanır.

• İzleme başına maliyet. Langfuse, maliyeti model adı ve token kullanımına göre hesaplar; bu nedenle izlemeleri maliyete göre sıralayın ve en maliyetli olanı baştan sona inceleyin. Sorun genellikle aşırı büyümüş bir istemdir: bağlama yapıştırılmış koca bir belge veya kimsenin kırpmadığı bir konuşma geçmişi. Bunu gördüğünüzde, bir yapay zeka aracısının maliyetini kontrol etmek, tahmin yürütmek yerine bir mühendislik görevine dönüşür.
• Girdi ve çıktıya göre token kullanımı dağılımı. Girdi tokenları çok sayıda ve ucuzdur, çıktı tokenları ise az sayıda ve pahalıdır; önbelleğe alınmış girdi ise daha da ucuzdur. Aynı hesaplama yöntemi Claude Code token kullanımının nasıl hesaplandığı bölümünde açıklanmıştır ve kendi yazdığınız her aracı için geçerlidir.
• Gecikme yüzdelikleri. Medyan değer sorunu gizler. p95 ve p99 değerleri zaman aşımlarının yaşandığı yerlerdir; bir aracı döngüsü içinde p95 seviyesindeki yavaş bir araç çağrısı, yineleme sayısıyla çarpılarak büyür.
• Başarısız araç çağrıları. Gözlemleri ERROR seviyesine göre filtreleyin. Yüzde 5 oranında başarısız olan bir araç, toplam başarı oranında görünmez ancak izlemelerde çok belirgindir; burada modelin tekrar deneme yaptığını ve sorunu aşmak için token harcadığını gözlemleyebilirsiniz.

Veri saklama süresini ayarlayın ve dağıtım yaptığınız günle aynı gün haftalık olarak kontrol edeceğiniz paneli seçin. Kimsenin açmadığı bir gözlemlenebilirlik aracı, sadece diski dolduran bir veritabanından ibarettir.

FAQ

Kendi kendine barındırılan (self-hosted) Langfuse ne kadar bellek gerektirir?

Tek bir sanal makine için Langfuse Docker Compose kılavuzunun önerdiği 4 CPU çekirdeği ve 16 GiB bellek ile yaklaşık 100 GiB depolama alanını planlayın. Yayınlanan bileşen minimumları ClickHouse için 8 GiB, web ve worker container'ları ile Postgres, Redis ve MinIO için ise bunların üzerine ek olarak gereken bellek miktarıdır. Sekiz GiB, tek bir geliştiricinin örneğini çalıştırır. İki GiB yeterli değildir: ClickHouse, arka plan birleştirmeleri sırasında çekirdek tarafından sonlandırılır ve dmesg, Out of memory: Killed process hatasını gösterir.

Veri saklama süresini ayarlamama rağmen ClickHouse diskim neden sürekli doluyor?

Saklama ayarı yalnızca Langfuse'un kendi verilerini kapsar. ClickHouse, trace_log, text_log, opentelemetry_span_log, metric_log ve asynchronous_metric_log tanı tablolarını ayrı olarak yazar ve bunlar herhangi bir TTL (yaşam süresi) ayarı olmadan gelir. Hangi tablonun en büyük olduğunu görmek için tabloya göre gruplandırılmış system.parts sorgusunu çalıştırın, ardından /etc/clickhouse-server/config.d/ altındaki bir dosyada remove="1" girdisi ile kullanılmayan tabloları devre dışı bırakın, ClickHouse'u yeniden başlatın ve halihazırda kullanılan alanı geri kazanmak için mevcut tabloları silin.

Langfuse'ta minimum veri saklama süresi nedir?

Üç gün. Saklama süresi, proje ayarlarından veya projeler API'si aracılığıyla proje bazında belirlenir; gece çalışan bir iş, belirtilen pencereden daha eski olan izleri (traces), gözlemleri, puanları ve medya varlıklarını hem ClickHouse'dan hem de blob depolamadan siler. Silme işlemi geri alınamaz, bu nedenle bu pencerenin ötesinde bir geçmişe ihtiyacınız varsa önce bir blob depolama dışa aktarma işlemi yapılandırın.

Hem Postgres hem de ClickHouse'u yedeklemek zorunda mıyım?

Evet, çünkü farklı verileri tutarlar. Postgres kullanıcıları, organizasyonları, projeleri ve API anahtarlarını tutarken, ClickHouse iz verilerinin kendisini tutar. Yalnızca Postgres'i geri yüklemek, oturum açabileceğiniz ancak içinde hiçbir şey olmayan bir örnekle sonuçlanır. MinIO bucket'ını da yedekleyin; çünkü bu, Langfuse'un ulaştığı anda kalıcı hale getirdiği ham olayları tutar ve bu, yığındaki (stack) gerçek veri kaynağına en yakın şeydir.

Mevcut bir OpenTelemetry kurulumunu kendi kendine barındırılan Langfuse'a yönlendirebilir miyim?

Evet. Langfuse v4 ve v4 SDK'ları OpenTelemetry üzerine inşa edilmiştir; Anthropic ve OpenAI OTel enstrümantasyonları doğrudan buraya dışa aktarım yapar. Python'da pip install langfuse opentelemetry-instrumentation-anthropic komutunu çalıştırın, başlangıçta bir kez AnthropicInstrumentor().instrument() çağrısını yapın ve LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY ile LANGFUSE_BASE_URL değerlerini kendi sunucunuza ayarlayın. Eksik bir panoyu aramaya başlamadan önce langfuse.auth_check() ile bağlantıyı doğrulayın.