Cara Self-Host Langfuse untuk Melacak AI Agent

Mengapa AI agent perlu dilacak

Anda melakukan self-host Langfuse untuk melihat tindakan agent saat dijalankan. Langfuse adalah alat observability open source untuk LLM (large language model). Alat ini mencatat setiap prompt, setiap respons model, setiap pemanggilan tool, dan setiap token, lalu mengelompokkannya dalam satu trace yang dapat Anda buka dan baca. Menjalankannya pada VPS milik sendiri berarti prompt tersebut tidak pernah meninggalkan server yang Anda kendalikan.

Alasannya sederhana. Anda tidak dapat memperbaiki masalah biaya atau kualitas yang tidak dapat Anda lihat. Invoice dari provider memberi tahu bahwa biaya pada hari Selasa empat kali lebih besar daripada biaya pada hari Senin. Trace memberi tahu agent run mana yang menyebabkannya, prompt mana yang bertambah hingga 40,000 token, dan retry loop mana yang berjalan sembilan kali sebelum berhenti. Invoice memberikan angkanya. Trace memberikan kode yang menghasilkan angka tersebut.

Tiga istilah digunakan di seluruh panduan ini. Trace adalah satu kali agent berjalan dari awal hingga akhir. Observation adalah satu langkah di dalam proses tersebut: span untuk kode biasa, dan generation untuk pemanggilan model. Score adalah angka yang dilampirkan pada trace, dari peninjauan manusia atau evaluator otomatis. Langfuse menggunakan OpenTelemetry (OTel), yaitu standar vendor-neutral untuk distributed tracing, sehingga instrumentation yang sudah Anda miliki dapat diarahkan ke sana.

Komponen yang benar-benar berjalan saat self-hosting Langfuse

Langfuse v4 bukan satu container. Langfuse terdiri atas dua container aplikasi dan empat layanan penyimpanan. Pada satu VPS, keenam komponen tersebut berjalan di server Anda.

• langfuse-web menyajikan antarmuka web dan API ingestion.
• langfuse-worker mengosongkan antrean di latar belakang. Komponen ini mem-parsing batch ingestion, menghitung biaya, dan menjalankan pekerjaan retensi setiap malam.
• Postgres menyimpan data transaksional, seperti pengguna, organisasi, project, API key, dan prompt.
• ClickHouse menyimpan data trace itu sendiri, yaitu observation dan score. ClickHouse adalah column store yang dibuat untuk query analitik. Karena itu, dashboard yang membaca lebih dari seratus juta baris tetap dapat memberikan respons dengan cepat.
• Redis adalah antrean dan cache yang berada di antara web dan worker.
• MinIO menyediakan object storage yang kompatibel dengan S3 di server Anda. MinIO menyimpan setiap event mentah yang masuk, serta media apa pun yang Anda lampirkan.

Langfuse memublikasikan kebutuhan minimum untuk tiga komponen yang menjalankan pekerjaan utama.

[
  {
    "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
  }
]

ClickHouse saja membutuhkan 8 GiB memori. Container web dan worker masing-masing membutuhkan 4 GiB. Angka tersebut adalah batas minimum yang dipublikasikan untuk 3 komponen yang dihitung oleh Langfuse. Postgres, Redis, dan MinIO tetap membutuhkan memori tambahan. Panduan Docker Compose resmi project ini merekomendasikan mesin dengan 4 core, memori 16 GiB, dan storage sekitar 100 GiB. Rekomendasi tersebut sesuai dengan perhitungan itu, bukan angka yang sengaja dilebihkan.

Jangan mencoba menjalankan ini pada paket 2 GiB. ClickHouse akan start dan menerima write selama beberapa saat, lalu berhenti saat background merge berjalan karena proses merge memuat part berukuran besar dari sebuah tabel ke memori. Anda akan melihat docker compose ps melaporkan container clickhouse sebagai restarting, dmesg membawa baris seperti Out of memory: Killed process 1234 (clickhouse-serv), dan setiap dashboard Langfuse mengembalikan status 500. Pada beban yang lebih ringan, ClickHouse akan menolak query dan mencatat DB::Exception: Memory limit (total) exceeded di log. Delapan GiB masih dapat digunakan oleh satu developer yang mengirim beberapa ribu trace per hari. Untuk perencanaan, gunakan 16 GiB.

Deploy Langfuse dengan Docker Compose

Clone repositori. Stack, konfigurasi koneksi, dan environment default semuanya berada dalam docker-compose.yml.

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

Setiap nilai yang harus Anda ubah ditandai dengan # CHANGEME dalam file tersebut. Buat terlebih dahulu tiga secret aplikasi.

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

ENCRYPTION_KEY harus berukuran 256 bit dan ditulis sebagai 64 karakter heksadesimal. Nilai tersebut dihasilkan tepat oleh openssl rand -hex 32. Secret ini mengenkripsi nilai sensitif saat disimpan, termasuk kunci penyedia LLM yang Anda simpan dalam instance. Jika diubah setelah data tersimpan, baris tersebut tidak dapat lagi didekripsi. Karena itu, anggap nilainya permanen sejak boot pertama. SALT digunakan untuk melakukan hashing pada API key Langfuse. Mengubahnya akan membatalkan semua key yang sudah digunakan agen Anda.

Selanjutnya, atur POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH, dan MINIO_ROOT_PASSWORD. Password MinIO muncul di empat tempat: pertama sebagai MINIO_ROOT_PASSWORD, lalu sebagai LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY, dan LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Jika salah satu terlewat, MinIO menolak client tersebut dengan SignatureDoesNotMatch. Pesan ini muncul dalam log worker, sementara antarmuka web tetap terlihat normal. Menyimpan nilai-nilai ini dalam file env, bukan dalam file compose yang dilacak, merupakan pola yang dibahas di file env dan secret Docker Compose.

Tetapkan tag image sebelum memulai

File yang disertakan menggunakan langfuse/langfuse:4 dan langfuse/langfuse-worker:4. Tag tersebut dapat berubah. Langfuse menjalankan migrasi Postgres dan ClickHouse secara otomatis saat start. Karena itu, docker compose pull rutin beberapa bulan kemudian dapat berubah menjadi migrasi skema yang tidak direncanakan pada database yang tidak Anda backup pagi itu. Tetapkan kedua image ke satu release dalam docker-compose.override.yml. Compose menggabungkan file ini di atas file yang disertakan, sehingga git pull berikutnya tidak menimpa perubahan Anda.

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

Version 4.3.1 merupakan release 4.3 terbaru pada Agustus 2026 (4.4.0 telah dirilis sejak saat itu). Periksa halaman release GitHub proyek, tetapkan versi yang sedang berlaku pada hari deployment, lalu ubah nomor tersebut secara sengaja. Image penyimpanan dalam file yang disertakan sudah ditetapkan ke major version, yaitu postgres:17, clickhouse-server:25.12, dan redis:7. Image tersebut juga perlu diperlakukan dengan cara yang sama.

Jalankan stack.

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

Boot pertama menjalankan migrasi. Tunggu satu atau dua menit sebelum mengharapkan respons. docker compose ps harus menampilkan enam service dalam status running. Jika worker terus restart dalam loop, alasannya tercantum dalam log: CLICKHOUSE_MIGRATION_URL menggunakan protokol native ClickHouse pada port 9000, bukan port HTTP 8123. Mengarahkannya ke 8123 menyebabkan kegagalan pada worker, sementara container web tetap terlihat normal.

Periksa health dari server itu sendiri.

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

Pemanggilan /api/public/health biasa hanya membuktikan bahwa proses API aktif, karena pemanggilan tersebut sengaja melewati database agar service tetap melayani request saat Postgres mengalami gangguan singkat. Bentuk failIfDatabaseUnavailable=true adalah endpoint yang sebaiknya dipantau. Endpoint tersebut mengembalikan 503 saat database tidak dapat dijangkau. /api/public/ready mengembalikan 200 setelah migrasi selesai dan container siap menerima trafik. Keduanya merupakan pemeriksaan HTTP biasa, sehingga halaman status Uptime Kuma dapat memantaunya dan memberi tahu Anda bahwa stack berhenti sebelum agen Anda menyadarinya.

Pasang TLS di depan dan tutup port tambahan

File Compose yang disertakan memublikasikan 3000:3000 untuk container web dan 9090:9000 untuk MinIO. Keduanya terikat pada semua interface. Pada IP publik, siapa pun yang memindai port 3000 dapat mencapai halaman pendaftaran Anda, dan siapa pun yang memindai port 9090 dapat mengakses bucket yang menyimpan prompt mentah Anda.

Aturan firewall saja tidak menutup port tersebut. Docker menulis aturan DNAT sendiri ke dalam tabel nat. Aturan itu dievaluasi sebelum paket diproses oleh aturan filter ufw, sehingga ufw deny 3000 membuat port yang dipublikasikan tetap terbuka. Masalah ini cukup umum sehingga memiliki panduan tersendiri: mengapa port yang dipublikasikan Docker melewati ufw. Sebagai gantinya, ikat port tersebut ke loopback dalam file override Anda.

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 harus berupa alamat publik yang tepat, termasuk skema, karena alur login membangun URL callback dari nilai tersebut. Jika nilainya dibiarkan sebagai http://localhost:3000 di belakang proxy HTTPS, proses bolak-balik saat login akan mengarahkan browser ke alamat yang tidak dapat dijangkaunya.

Selanjutnya, arahkan reverse proxy ke 127.0.0.1:3000 dan biarkan proxy tersebut mengelola sertifikat. Traefik dalam project Compose yang sama biasanya menjadi pilihan yang umum, dan label routing-nya dibahas dalam menjalankan beberapa aplikasi di balik satu reverse proxy Traefik. Caddy dapat melakukan tugas yang sama hanya dengan dua baris jika Langfuse adalah satu-satunya aplikasi di server. Verifikasi dengan curl -sI https://langfuse.example.com/api/public/ready, lalu pastikan dari mesin kedua bahwa curl http://YOUR_IP:3000 sekarang mengalami timeout.

Ada satu hal yang perlu diperhatikan terkait MinIO. Langfuse menyajikan media terlampir ke browser Anda melalui URL yang telah ditandatangani sebelumnya dan mengarah ke endpoint S3 tersebut. Karena itu, jika Anda menggunakan trace multimodal yang berisi gambar atau audio, MinIO yang hanya terikat ke loopback akan membuat lampiran tersebut tidak dapat dimuat. Baca halaman konfigurasi penyimpanan blob sebelum mem-proxy MinIO, karena endpoint yang ditulis ke dalam URL yang telah ditandatangani sebelumnya harus sesuai dengan endpoint yang Anda publikasikan. Trace teks biasa tidak terpengaruh.

Buat akun Anda saat pertama kali berkunjung, lalu pastikan instance tersebut tetap menjadi milik Anda. Atur LANGFUSE_ALLOWED_ORGANIZATION_CREATORS ke alamat email Anda sendiri agar orang asing yang mencapai halaman tersebut tidak dapat membuat organisasi di server Anda. Jika Anda sudah menjalankan Authentik sebagai penyedia identitas Anda sendiri, Langfuse mendukung koneksi OIDC standar. Dengan demikian, akun dapat dibuat dan dihapus bersama aplikasi Anda yang lain, bukan disimpan dalam daftar kata sandi yang hanya dikenal oleh server ini.

Kirim trace pertama Anda

Buat project melalui antarmuka web, lalu salin public key dan secret key dari pengaturan project. Python SDK membaca tiga variabel lingkungan.

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

LANGFUSE_BASE_URL adalah nama variabel dalam SDK v4, yang dirilis pada Maret 2026. Kode lama dan panduan lama menggunakan LANGFUSE_HOST. Jika trace Anda masuk ke Langfuse Cloud, bukan ke server Anda, penyebabnya adalah base URL belum disetel, karena nilai default mengarah ke instance yang di-host.

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()

Decorator @observe membuka observation di sekitar fungsi, menangkap argumen dan nilai yang dikembalikannya, lalu menempatkannya sebagai nested observation di bawah observation yang sedang aktif. AnthropicInstrumentor adalah instrumentasi OpenTelemetry untuk client Anthropic. Instrumentasi ini mengubah setiap pemanggilan messages.create menjadi generation yang memuat nama model, penggunaan token, dan latency, tanpa perubahan pada lokasi pemanggilan.

Dua pemanggilan berikut melakukan pemeriksaan untuk Anda. langfuse.auth_check() mengembalikan False jika key tidak valid atau base URL salah. Ini lebih cepat daripada mencari tahu mengapa dashboard kosong. langfuse.flush() menunggu hingga span yang berada dalam antrean terkirim. Fitur ini diperlukan untuk proses berumur singkat, karena SDK mengirim data secara batch di background dan script yang langsung keluar akan membawa serta batch yang belum terkirim.

Mengapa ClickHouse terus bertambah besar?

Traces adalah data yang pertumbuhannya paling cepat di antara data yang biasanya di-host sendiri. Setiap eksekusi agent menulis satu baris untuk setiap langkah. Input dan output juga disimpan secara lengkap. Karena itu, agent yang banyak menghasilkan pesan dengan prompt panjang dapat menghasilkan jauh lebih banyak byte per hari daripada aplikasi yang dipantaunya. Jika dibiarkan, ClickHouse akan memenuhi disk. Disk yang penuh akan menghentikan ingestion, bukan hanya memperlambatnya.

Ada dua hal terpisah yang bertambah besar di sini. Keduanya memerlukan perbaikan yang berbeda.

Yang pertama adalah data trace Anda sendiri. Perbaikannya adalah pengaturan retention. Buka pengaturan project pada antarmuka web, lalu tetapkan periode data retention dalam hari. Langfuse menerima minimum 3 hari. Selanjutnya, job malam memilih traces, observations, scores, dan media assets yang lebih lama daripada periode tersebut, lalu menghapusnya dari ClickHouse dan blob storage. Job ini memerlukan izin DeleteObject pada bucket. Kredensial root MinIO dalam file compose default sudah memiliki izin tersebut. Penghapusan bersifat permanen. Karena itu, konfigurasikan ekspor ke blob storage terlebih dahulu jika Anda memerlukan riwayat jangka panjang. Jangan menulis klausa TTL secara manual pada tabel milik Langfuse. Job retention menjaga ClickHouse dan bucket tetap selaras, sedangkan TTL manual hanya menghapus salah satunya.

Pilih periode berdasarkan data yang benar-benar Anda gunakan. Peninjauan biaya dan kualitas biasanya menggunakan data dari beberapa hari terakhir, bukan data dari beberapa bulan lalu. Tiga puluh hari adalah titik awal yang wajar untuk tim kecil. Empat belas hari cukup jika Anda hanya membuka trace ketika terjadi masalah.

Yang kedua adalah tabel system log milik ClickHouse. Hal ini sering mengejutkan karena disk tetap bertambah besar setelah retention dikonfigurasi. ClickHouse menulis trace_log, text_log, opentelemetry_span_log, metric_log, dan asynchronous_metric_log untuk diagnostiknya sendiri. Tabel-tabel tersebut tidak memiliki TTL secara default, dan Langfuse tidak pernah membacanya. Cari tahu terlebih dahulu ke mana disk sebenarnya digunakan.

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
)

Jalankan dengan docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Jika tabel system berada di bagian teratas, nonaktifkan tabel tersebut dengan config overlay. ClickHouse menggabungkan setiap file dalam /etc/clickhouse-server/config.d/ di atas konfigurasi utamanya saat start.

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

Mount file tersebut, lalu restart ClickHouse.

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

Tindakan ini menghentikan penulisan baru. Baris yang sudah ada di disk tetap berada di sana. Karena itu, ambil kembali ruang tersebut secara eksplisit dengan DROP TABLE IF EXISTS system.trace_log, lalu lakukan hal yang sama untuk setiap tabel yang Anda hapus. Jika Anda ingin tetap menyimpan diagnostik, gunakan TTL agresif pada setiap tabel sebagai alternatif untuk remove="1". Dokumentasi scaling Langfuse menjelaskan konfigurasi tersebut.

Ada satu tabel lain yang perlu diketahui. blob_storage_file_log mencatat file event yang diunggah ke bucket Anda. Jika Anda juga menetapkan lifecycle policy pada bucket, berikan TTL yang sesuai pada tabel tersebut agar keduanya tidak berjalan tidak selaras.

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

Tambahkan juga alert df -h sederhana pada data disk. Trace tidak bertambah secara bertahap. Pertumbuhannya dapat melonjak pada hari ketika Anda merilis agent baru. Tanda pertama kondisi tersebut seharusnya bukan kegagalan ingestion.

Cadangkan Postgres dan ClickHouse

Cadangan Langfuse terdiri dari tiga bagian. Postgres menyimpan pengguna, organisasi, proyek, dan API key Anda. ClickHouse menyimpan trace. MinIO menyimpan event mentah. Jika hanya Postgres yang dipulihkan, Anda mendapatkan login yang berfungsi tanpa riwayat. Jika hanya ClickHouse yang dipulihkan, Anda mendapatkan riwayat yang tidak dapat dilihat siapa pun karena tidak ada yang dapat login.

Postgres adalah pg_dump biasa. Cara ini direkomendasikan oleh dokumentasi cadangan Langfuse.

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

ClickHouse memerlukan penanganan yang lebih hati-hati, karena menyalin direktori data aktif saat proses merge berjalan tidak menghasilkan cadangan yang konsisten. Pada satu server, pendekatan sederhana adalah menghentikan container lalu mengarsipkan volume.

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

Gunakan nama volume yang ditampilkan oleh docker volume ls, bukan nama yang ditulis dalam YAML. File tersebut mendeklarasikan langfuse_clickhouse_data, lalu Compose menambahkan nama proyek sebagai prefix. Karena itu, clone di direktori bernama langfuse menghasilkan langfuse_langfuse_clickhouse_data. Jika nama tersebut salah, docker run akan membuat volume baru yang kosong tanpa menampilkan error, sehingga arsip Anda tidak berisi apa pun.

Web container menulis setiap event yang masuk ke bucket sebelum worker memprosesnya. Karena itu, penghentian ClickHouse dalam waktu singkat biasanya hanya membuat worker mencoba kembali setelahnya. Lakukan pada jam yang sepi dan batasi durasinya. Untuk instance yang lebih sibuk, statement BACKUP DATABASE default TO S3(...) milik ClickHouse membuat cadangan yang konsisten tanpa menghentikan server. MinIO adalah bagian ketiga, dan mc mirror atau replikasi MinIO ke bucket di luar server dapat mencadangkannya. Apa pun metode yang digunakan, simpan hasilnya di luar server. Itulah tujuan cadangan restic terenkripsi pada VPS.

Redis tidak memerlukan cadangan. Redis menyimpan queue dan cache, sehingga kehilangannya hanya menghapus event yang sedang diproses dan tidak memengaruhi data yang lebih lama.

Catatan tentang konsistensi ini penting dan perlu dinyatakan dengan jelas. Postgres dan ClickHouse dicadangkan pada waktu yang berbeda. Karena itu, pemulihan dapat menghasilkan baris proyek tanpa trace, atau trace yang merujuk ke proyek yang sudah tidak ada. Langfuse dapat menangani kondisi tersebut, tetapi buat kedua cadangan sedekat mungkin dan pada waktu dengan trafik rendah. Bucket event adalah pengaman utama, karena Langfuse menyimpan setiap event yang masuk di sana sebelum memprosesnya.

Pulihkan cadangan ke scratch stack setidaknya sekali. Dengan begitu, Anda dapat menemukan kesalahan nama volume sekarang, bukan saat terjadi gangguan layanan.

Hal yang perlu diperiksa terlebih dahulu

Empat hal berikut perlu Anda periksa pada minggu pertama.

• Biaya per trace. Langfuse menghitung biaya berdasarkan nama model dan penggunaan token. Urutkan trace berdasarkan biaya, lalu baca trace paling mahal dari awal sampai akhir. Biasanya penyebabnya adalah prompt yang terus bertambah: seluruh dokumen ditempelkan ke context, atau riwayat percakapan tidak pernah dipangkas. Setelah Anda dapat melihatnya, mengendalikan biaya AI agent menjadi tugas engineering, bukan perkiraan.
• Pembagian penggunaan token berdasarkan input dan output. Token input jumlahnya banyak dan murah, sedangkan token output jumlahnya sedikit dan mahal. Input yang di-cache bahkan lebih murah. Perhitungan yang sama dijelaskan dalam cara penghitungan penggunaan token Claude Code, dan berlaku untuk agent apa pun yang Anda tulis sendiri.
• Persentil latency. Nilai median dapat menyembunyikan masalah. p95 dan p99 adalah tempat timeout terjadi. Di dalam loop agent, pemanggilan tool yang lambat pada p95 dikalikan dengan jumlah iterasi.
• Pemanggilan tool yang gagal. Filter observation berdasarkan level ERROR. Tool yang gagal 5% dari waktu pemakaian dapat tidak terlihat dalam tingkat keberhasilan agregat, tetapi sangat terlihat dalam trace. Di sana Anda dapat memantau model mencoba lagi, lalu menghabiskan token untuk mengatasinya.

Tetapkan periode retensi dan pilih dashboard yang akan Anda periksa setiap minggu pada hari yang sama saat melakukan deployment. Tool observability yang tidak pernah dibuka adalah database yang akhirnya memenuhi disk.

FAQ

Berapa banyak memori yang dibutuhkan Langfuse yang di-hosting sendiri?

Siapkan 4 core CPU dan memori 16 GiB, sesuai rekomendasi panduan Langfuse Docker Compose untuk satu mesin virtual, serta penyimpanan sekitar 100 GiB. Nilai minimum komponen yang dipublikasikan adalah 8 GiB untuk ClickHouse dan masing-masing 4 GiB untuk container web dan worker. Postgres, Redis, dan MinIO juga memerlukan memori tambahan. Delapan GiB cukup untuk instance milik satu developer. Dua GiB tidak cukup: ClickHouse dihentikan kernel saat melakukan merge di latar belakang, dan dmesg menampilkan Out of memory: Killed process.

Mengapa disk ClickHouse terus penuh setelah saya menetapkan retensi data?

Pengaturan retensi hanya mencakup data milik Langfuse. ClickHouse secara terpisah menulis tabel diagnostik trace_log, text_log, opentelemetry_span_log, metric_log, dan asynchronous_metric_log, yang tidak memiliki TTL. Jalankan kueri system.parts yang dikelompokkan berdasarkan tabel untuk melihat tabel terbesar. Kemudian nonaktifkan tabel yang tidak digunakan dengan entri remove="1" dalam file di bawah /etc/clickhouse-server/config.d/, restart ClickHouse, lalu hapus tabel yang sudah ada untuk mendapatkan kembali ruang yang telah digunakan.

Berapa periode retensi data minimum di Langfuse?

Tiga hari. Retensi ditetapkan per proyek dalam pengaturan proyek atau melalui projects API. Pekerjaan yang berjalan setiap malam akan menghapus trace, observasi, skor, dan aset media yang lebih lama dari periode tersebut dari ClickHouse dan blob storage. Penghapusan tidak dapat dibatalkan. Konfigurasikan ekspor ke blob storage terlebih dahulu jika Anda memerlukan histori di luar periode tersebut.

Apakah saya harus mencadangkan Postgres dan ClickHouse?

Ya, karena keduanya menyimpan data yang berbeda. Postgres menyimpan pengguna, organisasi, proyek, dan API key. ClickHouse menyimpan data trace itu sendiri. Pemulihan yang hanya menggunakan cadangan Postgres menghasilkan instance yang dapat Anda masuki, tetapi tidak berisi data. Cadangkan bucket MinIO juga karena bucket tersebut menyimpan event mentah yang dipersistenkan Langfuse saat diterima. Data ini adalah hal yang paling mendekati sumber kebenaran dalam stack tersebut.

Dapatkah saya mengarahkan setup OpenTelemetry yang sudah ada ke Langfuse yang di-hosting sendiri?

Ya. Langfuse v4 dan SDK v4-nya dibangun di atas OpenTelemetry. Instrumentasi OTel Anthropic dan OpenAI dapat mengekspor data langsung ke Langfuse. Di Python, jalankan pip install langfuse opentelemetry-instrumentation-anthropic, panggil AnthropicInstrumentor().instrument() sekali saat startup, lalu tetapkan LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, dan LANGFUSE_BASE_URL ke host Anda sendiri. Konfirmasikan dengan langfuse.auth_check() sebelum mencari penyebab dashboard yang tidak menampilkan data.