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üne ve ingestion API'sine hizmet eder.
• langfuse-worker arka planda kuyruğu boşaltır. Ingestion yığınlarını ayrıştırır, maliyeti hesaplar ve gece çalışan saklama (retention) işini yürütür.
• Postgres; kullanıcılar, organizasyonlar, projeler, API anahtarları ve istemler gibi işlemsel verileri tutar.
• ClickHouse, izleme verilerinin kendisini, yani gözlemleri ve puanları tutar. Analitik sorgular için oluşturulmuş bir sütun tabanlı depolama birimidir; yüz milyon 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, çalıştırdığı her bileşen için minimum kaynak gereksinimlerini yayınlar. Aşağıdaki tablo iş yükünü üstlenen üç bileşeni göstermektedir.

[
  {
    "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 her biri için 4 GiB talep eder. Bunlar, tablodaki 3 bileşen için yayınlanan alt sınırlardır. Aynı sayfada Postgres 4 GiB, Redis veya Valkey 1.5 GiB ve MinIO 4 GiB olarak listelenmiştir; dolayısıyla altı bileşenin toplam minimum gereksinimi 25.5 GiB'a ulaşır. Projenin kendi Docker Compose kılavuzu, tek bir makine için en az 4 çekirdek, 16 GiB bellek ve yaklaşık 100 GiB depolama alanı önermektedir. Bu değer, bileşenlerin minimum gereksinimlerinin toplamından daha düşüktür; bu nedenle 16 GiB değerini bir boşluk payı olarak değil, paylaşımlı bir Compose sunucusu için gereken mutlak alt sınır olarak değerlendirin.

Bunu 2 GiB'lık bir plan üzerinde 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 bölümlerini belleğe yükler. Bu durumda docker compose ps üzerinde clickhouse container'ının restarting durumunda olduğunu görürsünüz, dmesg üzerinde Out of memory: Killed process 1234 (clickhouse-serv) gibi bir satır yer alır ve tüm Langfuse dashboard'ları 500 hatası döndürür. Daha hafif yük altında ise ClickHouse sorguyu reddeder ve DB::Exception: Memory limit (total) exceeded günlüğünü oluşturur. Planlama yaparken baz almanız gereken sayı 16'dır. Eğer aynı VPS üzerinde başka servisler de çalışacaksa, bunlar için ayrı bir bütçe ayırın; çünkü self-hosted bir AFFiNE çalışma alanı gibi nispeten hafif bir yığın bile kendi gigabaytlarına ihtiyaç duyar ve ClickHouse kullandığı belleği geri vermez.

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ı (secret) 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 (hex) karakterden oluşan 256 bitlik bir değer olmalıdır; openssl rand -hex 32 komutu tam olarak bunu üretir. Bu anahtar, instance içerisinde sakladığınız LLM sağlayıcı anahtarları dahil olmak üzere, diskteki hassas verileri şifreler. Veri oluştuktan sonra bu anahtarı 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ı hash'lemek 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 görünür: 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 olarak. Birini bile atlarsanız MinIO istemciyi SignatureDoesNotMatch hatası ile reddeder; bu hata worker günlüğüne düşerken web arayüzü sağlıklı görünmeye devam edebilir. Bu değerleri takip edilen compose dosyası yerine bir env dosyasında tutmak, Docker Compose env dosyaları ve gizli anahtarlar bölümünde açıklanan yöntemdir.

Başlamadan önce imaj etiketlerini sabitleyin

Dağıtılan dosya docker.langfuse.com/langfuse/langfuse:4 ve docker.langfuse.com/langfuse/langfuse-worker:4 kullanır. Bu etiketler zamanla değişir. Langfuse, Postgres ve ClickHouse migrasyonlarını başlangıçta otomatik olarak çalıştırır; bu nedenle aylar sonra yapılan rutin bir docker compose pull işlemi, o sabah yedeklemediğiniz bir veritabanında planlanmamış bir şema migrasyonuna dönüşebilir. Her ikisini de bir docker-compose.override.yml içerisinde tek bir sürüme sabitleyin. Compose, bu dosyayı dağıtılan dosyanın üzerine ekler; böylece daha sonra yapılan bir git pull işlemi düzenlemelerinizle çakışmaz. Aynı imajlar Docker Hub üzerinde yayınlanır ve aşağıdaki geçersiz kılma (override) işlemi bunları oradan çeker.

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

Sürüm 4.3.1, Ağustos 2026 itibarıyla güncel 4.3 sürümüydü. O tarihten bu yana sürümler hızla yayınlandı ve 11 Ekim 2026 itibarıyla GitHub'daki en son sürüm v4.56.0 idi. Yukarıdaki geçersiz kılma işlemi, 31 Ekim 2026 itibarıyla GitHub'daki en son sürüm olan v4.72.0'ı kullanmaktadır. Projenin GitHub sürümleri sayfasını kontrol edin, kurulum yaptığınız gün güncel olan sürümü sabitleyin ve ardından bu numarayı bilinçli bir şekilde güncelleyin. Dağıtılan dosyadaki bazı depolama imajları da aynı muameleyi hak eder, çünkü onların da etiketleri değişir. postgres:17 (bir POSTGRES_VERSION değişkeninin varsayılanı) ve redis:7 ana sürümü takip eder. Dağıtılan dosya artık docker.io/clickhouse/clickhouse-server için tam bir sürüm etiketi kullanarak ClickHouse sürümünü sabitlemektedir. Bu kural yalnızca Langfuse'a özgü değildir: self-hosted bir openGym antrenman takipçisi bu yığının bir kısmını çalıştırır ve yine de adlandırılmış bir git etiketi ister; çünkü başlangıçta kendi veritabanını migre eden her şey, rutin bir çekme işlemini şema değişikliğine dönüştürebilir.

Sistemi ayağa kaldırın.

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

İlk başlatma migrasyonları çalıştırır, bu nedenle herhangi bir yanıt almadan önce iki veya üç dakika bekleyin. Web container'ı ayağa kalktığında Ready günlüğünü yazar. docker compose ps, running durumunda altı servis listelemelidir. Eğer bir container döngüsel olarak yeniden başlıyorsa, günlüğü nedenini içerir. ClickHouse migrasyonları web container'ı başladığında uygulanır, bu nedenle hatalı bir CLICKHOUSE_MIGRATION_URL, takip ettiğiniz worker günlüğünde değil, docker compose logs langfuse-web içerisinde görünür. Bu değişken, 8123 numaralı HTTP portunu değil, 9000 numaralı porttaki ClickHouse yerel protokolünü kullanır; 8123'e yönlendirmek web container'ının başlangıç migrasyonlarını bozar. Worker daha yavaş olan arka plan migrasyonlarını çalıştırır, bu nedenle bu hatalar onun günlüğünde raporlanır.

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ı, varsayılan olarak veritabanını kontrol etmediği için yalnızca API sürecinin canlı olduğunu kanıtlar. İzleme aracına eklenmesi gereken form failIfDatabaseUnavailable=true formudur; veritabanına ulaşılamadığında 503 döner. /api/public/ready, web container'ı trafiği kabul etmeye hazır olduğunda 200, kapatılması komutu verildiğinde ise 500 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'i ö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ı kapatmaz. 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, açılan portu açık bırakır. Bu durum, kendi rehberine sahip olacak kadar çok kişiyi etkilemektedir: Docker'ın açtığı portlar neden ufw'yi bypass eder. Bunun yerine override dosyanızda loopback adresine bağlayın. Açılan portları değiştirmek için Docker Compose 2.24.4 veya sonraki sürümlerinde !override kullanın; düz bir liste, orijinal bağlamalarla birleşir.

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

NEXTAUTH_URL, giriş akışı geri çağırma URL'sini bu değerden oluşturduğu için şemayı da içeren tam genel adres olmalıdır. Bir HTTPS proxy 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 için, bir Traefik reverse proxy arkasında birden fazla uygulama çalıştırma bölümünde ele alınan etiketleri kullanarak Compose ağı üzerinden langfuse-web:3000 adresine yönlendirme yapın. Sunucuda yalnızca 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 adresine bağlantı kurulamadığını teyit edin.

MinIO ile ilgili bir uyarı: Langfuse, hem medya yükleyen SDK'lara hem de onu yükleyen tarayıcınıza, o S3 uç noktasına işaret eden önceden imzalanmış (presigned) URL'ler verir. Bu nedenle, görüntü veya ses taşıyan çok modlu izler (multi-modal traces) kullanıyorsanız, yalnızca loopback'e bağlı bir MinIO, bu eklerin diğer makinelerden yüklenemeyeceği veya tarayıcınızda görüntülenemeyeceği anlamına gelir. Proxy'lemeden önce blob depolama yapılandırma sayfasını okuyun, çünkü önceden imzalanmış URL'ye yazılan LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT uç noktası, yayınladığınız adresle eşleşmelidir. Düz metin izleri bundan etkilenmez.

İlk ziyarette hesabınızı oluşturun, ardından instance'ı kendinize özel tutun. Hesabınız oluştuktan sonra AUTH_DISABLE_SIGNUP=true ayarını yapın; böylece sayfaya ulaşan bir yabancı kayıt olamaz. Langfuse ayrıca, kimlerin organizasyon oluşturabileceğini sınırlayan LANGFUSE_ALLOWED_ORGANIZATION_CREATORS özelliğine de sahiptir, ancak bu bir Enterprise Edition özelliğidir ve yalnızca bir lisans anahtarı ile devreye girer. 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, yalnızca 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. Eski kodlar ve eski kılavuzlar LANGFUSE_HOST kullanır. İzlemeleriniz sunucunuz yerine Langfuse Cloud'a ulaşıyorsa, bunun nedeni ayarlanmamış bir base URL'dir; çünkü varsayılan değer barındırılan (hosted) örneği işaret eder.

Mevcut Python SDK v5, Python 3.11 veya üzerini ve yukarıda sabitlenmiş sunucu sürümü olan Langfuse v4.59.0 veya üzerini gerektirir.

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ü, fonksiyonun 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) haline getirir; çağrı noktasında herhangi bir değişiklik gerektirmez.

İki çağrı sizin yerinize kontrolü gerçekleştirir. langfuse.auth_check(), hatalı anahtarlar veya yanlış bir base 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çler buna ihtiyaç duyar çünkü SDK arka planda toplu işlem (batch) yapar ve hemen sonlanan bir betik, gönderilmemiş toplu veriyi de beraberinde götürür. Eğer tek bir betik yerine tüm ekip izleme gönderiyorsa, bu üç değişkeni her kişinin kabuğunda (shell) ayarlamak yerine, herkesin aracısının üzerinden geçtiği ağ geçidinde bir kez ayarlayın. Kendi kendine barındırılan bir OneCLI donanımı, anahtarları tek bir yerde tutarken her iş arkadaşının çalışmasını bu şekilde enstrümante edilmiş halde tutar.

ClickHouse neden sürekli büyüyor?

İzleme verileri (traces), çoğu kişinin kendi sunucusunda barındırdığı en hızlı büyüyen veri türüdür. Her aracı (agent) çalışması, her adım için bir satır yazar; girdi ve çıktılar tam olarak depolanır. Bu nedenle, uzun istemlere sahip konuşkan bir aracı, izlediği uygulamadan günde ç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 bunların iki ayrı çözümle yönetilmesi gerekir.

Birincisi kendi izleme verilerinizdir; bunun çözümü bekletme (retention) ayarıdır. Kendi sunucunuzda barındırdığınız bir örnekte, veri bekletme özelliği Enterprise Edition kapsamında sunulur ve bir lisans anahtarı gerektirir. Lisans anahtarı olmadığında Langfuse; izlemeleri, gözlemleri, puanları ve medyaları süresiz olarak saklar. Bu durumda disk boyutunu buna göre planlamalı ve bu bölümün sonundaki disk uyarısına güvenmelisiniz. Lisansınız varsa, proje sahipleri ve yöneticileri proje ayarlarına giderek gün cinsinden bir veri bekletme süresi belirleyebilir. Langfuse en az 3 günlük bir süre kabul eder. Gece çalışan bir görev, bu pencereden daha eski olan izlemeleri, gözlemleri, puanları ve medya varlıklarını seçer; kaydedilmiş veri kümesi öğeleriyle ilişkili medyalar hariç olmak üzere bunları ClickHouse'dan ve blob depolama alanından siler. Bu görev, varsayılan compose dosyasındaki MinIO root kimlik bilgileriyle halihazırda sahip olunan DeleteObject iznine ihtiyaç duyar. 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 mekanizma bekletme görevidir; manuel bir TTL yalnızca bir taraftaki veriyi siler.

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

İkincisi ise ClickHouse'un kendi sistem günlük tablolarıdır. Bekletme ayarları 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, asynchronous_metric_log ve latency_log tablolarına yazma yapar; bunlar herhangi bir TTL olmadan gelir ve Langfuse bunları asla okumaz. Ö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 en üstündeyse, 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"/>
    <latency_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. Diskte halihazırda bulunan satırlar orada kalmaya devam eder; bu nedenle alanı DROP TABLE IF EXISTS system.trace_log komutuyla ve kaldırdığınız her tablo için aynı işlemi yaparak manuel olarak geri kazanın. Tanılama verilerini tutmak isterseniz, remove="1" yerine her tablo üzerinde agresif bir TTL kullanmak bir alternatiftir; bu yöntem Langfuse ölçeklendirme belgelerinde açıklanmıştır. Bu TTL yönergeleri yalnızca bir sistem tablosu ilk oluşturulduğunda geçerli olur; bu nedenle mevcut bir kurulumda aynı belgeler, tabloları geriye dönük olarak güncelleme konusunda size yol gösterecektir.

Bilmeniz gereken bir tablo daha vardır. blob_storage_file_log, depolama alanınıza yüklenen olay dosyalarını takip eder. 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;

Veri diski üzerinde basit bir df -h uyarısı da oluşturun. İzleme verileri düzenli bir şekilde büyümez. Yeni bir aracı yayınladığı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 üç parçadan 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 olay verilerini barındırır. Yalnızca Postgres'i geri yüklerseniz, geçmiş verisi 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. Bu ayrım yalnızca Langfuse'a özgü değildir; kendi sunucunuzda barındırdığınız bir Chatwoot destek masası da aynı yapıya sahiptir; burada uploads dizini olmadan alınan bir Postgres dökümü, ekleri kaybolmuş konuşmaları geri yükler.

Postgres, Langfuse yedekleme belgelerinin Docker kurulumu için önerdiği standart bir pg_dump işlemidir.

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ısı olan volume adını kullanın. Dosya langfuse_clickhouse_data değerini tanımlar, ancak Compose buna proje adını önek 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.

Langfuse, her veri alım isteğinde ham olay verilerini bucket'a yükler ve başarısız olan işleri yeniden denemek için bunları tekrar okur; bu nedenle ClickHouse'un kısa süreli durdurulması, worker'ın sonrasında yeniden deneme yapacağı 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 sunucu dışındaki bir bucket'a MinIO replikasyonu bu ihtiyacı karşılar. Ne üretirseniz üretin, veriyi sunucudan dışarı çıkarın; bir VPS üzerinde şifreli restic yedekleri tam olarak bunun içindir.

Redis kuyruğu ve önbelleği tutar. Redis'in kaybedilmesi, ham olay dosyaları bucket'ta kalsa bile kuyruktaki işlerin atılmasına neden olur.

Tutarlılık uyarısı gerçektir ve açıkça belirtilmelidir. Postgres ve ClickHouse farklı anlarda döküldüğü için, geri yükleme işlemi izleri olmayan bir proje satırı veya artık var olmayan bir projeye ait izler bırakabilir. 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 veri alım isteğinde ham olay verilerini oraya yükler.

En az bir kez boş bir stack üzerine geri yükleme denemesi yapın. Yanlış volume adını bir kesinti anında değil, şimdi öğrenmenin 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 sunucumda barındırdığım Langfuse ne kadar bellek gerektirir?

Tek bir sanal makine için Langfuse Docker Compose rehberinin ö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ının her biri için 4 GiB'dir. Aynı sayfada Postgres için 4 GiB, Redis için 1.5 GiB ve MinIO için 4 GiB listelenmiştir; bu durumda altı bileşenin toplamı 25.5 GiB eder ki bu da 16 GiB'lik Compose önerisinden fazladır.

Veri saklama süresini ayarlamama rağmen ClickHouse diskim neden dolmaya devam ediyor?

Saklama ayarı yalnızca Langfuse'un kendi verilerini kapsar. ClickHouse, trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log ve latency_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'da minimum veri saklama süresi nedir?

Üç gün. Saklama süresi, proje ayarlarından veya Organization Management API aracılığıyla proje bazında belirlenir. Gece çalışan bir iş; izleri (traces), gözlemleri (observations), puanları (scores) ve medya varlıklarını, kaydedilmiş veri kümesi öğeleriyle ilişkili olanlar hariç, belirlenen pencereden daha eski olanları hem ClickHouse'dan hem de blob depolamadan siler. Kendi sunucunuzda barındırdığınız örnekte bu, lisans anahtarı gerektiren bir Enterprise Edition özelliğidir. Lisans anahtarı olmadan veriler süresiz olarak tutulur. Silme işlemi geri alınamaz; bu nedenle, o pencerenin ötesinde bir geçmişe ihtiyacınız varsa önce bir blob depolama yedeği yapılandırın.

Hem Postgres hem de ClickHouse yedeğini almalı 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, giriş yapabileceğiniz ancak içinde hiçbir şey olmayan bir örnekle sonuçlanır. MinIO bucket'ının da yedeğini alın; çünkü burası 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 sunucumdaki Langfuse'a yönlendirebilir miyim?

Evet. Langfuse v4 ve mevcut SDK'ları OpenTelemetry üzerine inşa edilmiştir; Anthropic ve OpenAI OTel enstrümantasyonları doğrudan buraya veri aktarır. 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 ve LANGFUSE_BASE_URL değerlerini kendi sunucunuza ayarlayın. Eksik bir dashboard aramadan önce langfuse.auth_check() ile doğrulamayı yapın.