Kendi Sunucunuzda Langfuse Kurulumu ve Yapılandırması

Neden bir yapay zeka aracısını izlemelisiniz

Langfuse uygulamasını, aracınızın bir çalışma sırasında gerçekte ne yaptığını görmek için kendi sunucunuzda barındırırsınız. 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'ı kaydeder; ardından bunları açıp okuyabileceğiniz tek bir izleme (trace) altında gruplandırır. Bunu kendi VPS'nizde çalıştırmak, bu istemlerin kontrolünüz altındaki bir sunucudan asla ayrılmadığı anlamına gelir.

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 ise size bunu hangi aracı çalışmasının yaptığını, hangi istemin 40,000 token'a ulaştığını ve hangi yeniden deneme döngüsünün pes etmeden önce dokuz kez çalıştığını gösterir. Fatura size sayıyı verir. İzleme ise bu sayıyı üreten kodu verir.

Bu kılavuz boyunca üç terim kullanılır. İzleme (trace), aracınızın uçtan uca tek bir çalışma sürecidir. Gözlem (observation), bu çalışma içindeki tek bir adımdır: normal kod için bir span, modele yapılan bir çağrı için bir generation. Puan (score), bir insan incelemesinden veya otomatik bir değerlendiriciden gelen, bir izlemeye eklenmiş bir sayıdır. 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ı bu sisteme yönlendirebilirsiniz.

Langfuse self-hosting kurulumunda neler çalışır

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ı sunucunuzda ç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, 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 gibi işlemsel verileri tutar.
• ClickHouse; gözlemler ve skorlar dahil olmak üzere izleme (trace) verilerinin kendisini tutar. Analitik sorgular için oluşturulmuş bir sütun tabanlı depolama birimidir; 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 üç 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 talep eder. Bunlar, Langfuse'un boyutlandırdığı 3 bileşen için yayınlanan alt sınırlardır; Postgres, Redis ve MinIO'nun da bunlara ek olarak belleğe ihtiyacı vardır. Projenin kendi Docker Compose kılavuzu, bu aritmetikle örtüşen ve fazladan şişirme içermeyen, 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 kısımlarını belleğe yükler. Bu durumda docker compose ps komutunun clickhouse container'ını restarting olarak raporladığını, dmesg çıktısında Out of memory: Killed process 1234 (clickhouse-serv) gibi bir satırın yer aldığını ve tüm Langfuse dashboard'larının 500 hatası döndürdüğünü görürsünüz. Daha hafif yük altında ise ClickHouse sorguyu reddeder ve loglara DB::Exception: Memory limit (total) exceeded hatasını yazar. Günde birkaç bin izleme verisi gönderen tek bir geliştirici için 8 GiB bellek çalışabilir durumdadır. Planlanması gereken değer 16'dır.

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 o 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 karakterden oluşan 256 bitlik bir değer olmalıdır; openssl rand -hex 32 tam olarak bunu üretir. Bu değer, örnekte sakladığınız LLM sağlayıcı anahtarları dahil olmak üzere, diskteki hassas verileri şifreler. Veri oluştuktan sonra bu değeri değiştirmek, mevcut satırların şifresinin çözülememesine neden olur; bu nedenle ilk açılıştan itibaren kalıcı olarak kabul edin. 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 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 olarak. Birini bile atlarsanız 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 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ılacak rutin bir docker compose pull işlemi, o sabah yedeklemediğiniz bir veritabanında planlanmamış bir şema migrasyonuna dönüşür. Her ikisini de bir docker-compose.override.yml içerisinde belirli bir sürüme sabitleyin; Compose bunu dağıtılan dosyanın üzerine ekler, 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

Sürüm 4.3.1, Ağustos 2026 itibarıyla güncel 4.3 sürümüydü (4.4.0 sürümü o tarihten sonra yayınlandı). Projenin GitHub sürümler 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 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ış migrasyonları çalıştırır, bu yüzden yanıt almadan önce bir veya iki dakika bekleyin. docker compose ps, running durumunda altı servis listelemelidir. Eğer worker sürekli 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; 8123'e yönlendirmek burada başarısızlığa yol açarken web container'ı sağlıklı görünmeye devam eder.

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ı, veritabanını kasıtlı olarak atladığı için yalnızca API sürecinin canlı olduğunu kanıtlar; 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öndürür. /api/public/ready, migrasyonlar tamamlandığında ve container trafiği kabul etmeye hazır olduğunda 200 döndürür. 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 fazladan 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üzlerde dinleme yapar. Genel bir IP adresi üzerinde bu, port 3000'i tarayan herkesin kayıt sayfasına ulaşabileceği ve 9090'ı 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, dışarıya açılan portu açık bırakır. Bu durum o kadar çok kişiyi etkilemektedir ki, kendi rehberine sahiptir: Docker'ın dışarıya açtığı portlar neden ufw'yi atlatır. Bunun yerine override dosyanızda loopback arayüzüne 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 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 projesi içindeki Traefik yaygın bir tercihtir ve yönlendirme etiketleri bir Traefik reverse proxy arkasında birden fazla uygulama çalıştırma rehberinde ele alınmıştır. 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 adresinin artık zaman aşımına uğradığını teyit edin.

MinIO ile ilgili bir uyarı: Langfuse, ekli medyaları tarayıcınıza o S3 uç noktasına işaret eden önceden imzalanmış (presigned) URL'ler aracılığıyla sunar. Bu nedenle, görsel veya ses içeren çok modlu izlemeler (traces) kullanıyorsanız, yalnızca loopback üzerinde çalışan 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 izlemeleri bundan 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.

İ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ğe 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 yuvalar. 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 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 için bu gereklidir; çü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 kişinin 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ılar tam olarak saklanır; bu nedenle uzun istemlere sahip yoğun bir aracı, izlediği uygulamadan günlük bazda ç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 için iki ayrı çözüm gerekir.

Birincisi kendi izleme verilerinizdir; bunun çözümü saklama (retention) ayarıdır. Web arayüzünden proje ayarlarını açın ve gün cinsinden bir veri saklama süresi belirleyin. Langfuse en az 3 günlük bir süre kabul eder. Gece çalışan bir iş (job), bu pencereden daha eski olan izlemeleri, gözlemleri, puanları ve medya varlıklarını seçerek bunları ClickHouse'dan ve blob depolama alanından siler. Bu işin, varsayılan compose dosyasındaki MinIO root kimlik bilgileriyle halihazırda 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 saklama işidir; manuel bir TTL yalnızca bir tarafı 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 verilerini açıyorsanız 14 gün yeterlidir.

İkincisi ise ClickHouse'un kendi sistem günlük tablolarıdır. Bu durum kullanıcıları şaşırtır çünkü saklama ayarları yapılandırıldıktan sonra bile disk büyümeye devam eder. ClickHouse kendi tanılamaları için trace_log, text_log, opentelemetry_span_log, metric_log ve asynchronous_metric_log tablolarına yazma yapar; bunlar herhangi bir TTL olmadan gelir ve Langfuse bunları asla okumaz. Öncelikle diskin gerçekte 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 kapatı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 alanı DROP TABLE IF EXISTS system.trace_log komutuyla ve kaldırdığınız her tablo için aynı işlemi yaparak açıkça geri kazanın. Tanılama verilerini tutmak isterseniz, remove="1" yerine her tablo üzerinde agresif bir TTL uygulamak bir alternatiftir; bu konu Langfuse ölçeklendirme belgelerinde detaylandırılmıştır.

Hakkında bilgi sahibi olunması 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, tablonun da uyumlu bir TTL'ye sahip olduğundan emin olun; 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 olayları (raw events) saklar. Sadece Postgres'i geri yüklerseniz, geçmişi olmayan çalışan bir giriş ekranı elde edersiniz. Sadece 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'ı durdurup 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 tanımlar, ancak Compose buna proje adını önek olarak ekler; bu nedenle langfuse adlı bir dizindeki klon, langfuse_langfuse_clickhouse_data adını ü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 her gelen 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ışı bir bucket'a replikasyonu bu ihtiyacı karşılar. Ne üretirseniz üretin, veriyi sunucudan dışarı çıkarın; VPS üzerinde şifreli restic yedekleri tam olarak bunun içindir.

Redis yedekleme gerektirmez. Kuyruğu ve önbelleği tutar; bu nedenle Redis'in kaybedilmesi, yalnızca o an işlenmekte olan olayların kaybına yol açar, 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 izi 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 gelen olayı işlemeden önce orada kalıcı hale getirir.

En az bir kez boş bir stack üzerine geri yükleme yapın. Yanlış volume adını bir kesinti anında değil, şimdi öğrenmenin yolu budur.

What to look at first

Four things earn their place in the first week.

• Cost per trace. Langfuse computes cost from the model name and the token usage, so sort traces by cost and read the most expensive one end to end. The answer is usually a prompt that grew: a whole document pasted into context, or a conversation history nobody trims. Once you can see it, controlling what an AI agent costs you becomes an engineering task instead of a guess.
• Token usage split by input and output. Input tokens are numerous and cheap, output tokens are few and expensive, and cached input is cheaper again. The same accounting is unpacked in how Claude Code token usage is counted, and it applies to any agent you write yourself.
• Latency percentiles. The median hides the problem. p95 and p99 are where the timeouts live, and inside an agent loop a slow tool call at p95 gets multiplied by the number of iterations.
• Failed tool calls. Filter observations by level ERROR. A tool that fails 5% of the time is invisible in an aggregate success rate and very visible in the traces, where you watch the model retry and then burn tokens working around it.

Set the retention window and pick the dashboard you will check weekly on the same day you deploy. An observability tool nobody opens is a database that fills a disk.

FAQ

Self-hosted Langfuse ne kadar bellek gerektirir?

Dört CPU çekirdeği ve 16 GiB bellek planlayın; Langfuse Docker Compose rehberinin tek bir sanal makine için önerdiği değer budur. Ayrıca yaklaşık 100 GiB depolama alanı gerekir. Yayınlanan bileşen minimumları ClickHouse için 8 GiB, web ve worker container'ları için 4 GiB'dir; Postgres, Redis ve MinIO için de ek bellek gereklidir. Sekiz GiB bellek, tek bir geliştirici örneğini çalıştırır. İki GiB bellek yeterli değildir: ClickHouse, arka plan birleştirme işlemleri 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 dolmaya devam ediyor?

Saklama ayarı yalnızca Langfuse'un kendi verilerini kapsar. ClickHouse, trace_log, text_log, opentelemetry_span_log, metric_log ve asynchronous_metric_log gibi tanı tablolarını ayrı olarak yazar ve bunlar varsayılan bir TTL ile gelmez. Hangi tablonun en büyük olduğunu görmek için system.parts sorgusunu tabloya göre gruplayarak ç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ş, belirlenen süreden daha eski olan izleri (traces), gözlemleri, puanları ve medya varlıklarını hem ClickHouse'dan hem de blob depolama alanından siler. Silme işlemi geri alınamaz; bu nedenle, bu sürenin ö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 yedeklemem gerekiyor mu?

Evet, çünkü farklı verileri tutarlar. Postgres kullanıcıları, organizasyonları, projeleri ve API anahtarlarını; ClickHouse ise iz verilerinin kendisini tutar. Yalnızca Postgres'i geri yüklemek, içine giriş yapabileceğiniz ancak içi boş 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 gerçek veri kaynağına en yakın şeydir.

Mevcut bir OpenTelemetry kurulumunu self-hosted Langfuse'a yönlendirebilir miyim?

Evet. Langfuse v4 ve v4 SDK'ları OpenTelemetry üzerine kuruludur; 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() fonksiyonunu çağırın ve LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY ve LANGFUSE_BASE_URL değişkenlerini kendi sunucunuza göre ayarlayın. Eksik bir dashboard aramadan önce langfuse.auth_check() ile bağlantıyı doğrulayın.