SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor

Cara Self-Host Langfuse untuk Melacak AI Agent

Pelajari cara menjalankan Langfuse di VPS sendiri, termasuk kebutuhan resource minimum, image tag yang dipatok, TLS, retensi ClickHouse, dan backup yang dapat dipulihkan.

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 sebenarnya dijalankan oleh self-hosting Langfuse

Langfuse v4 bukan satu container. Langfuse terdiri atas dua container aplikasi dan empat service penyimpanan. Pada satu VPS, keenamnya berjalan di server Anda.

  • langfuse-web menyediakan antarmuka web dan API ingestion.
  • langfuse-worker mengosongkan queue di latar belakang. Service ini memproses batch ingestion, menghitung biaya, dan menjalankan tugas 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 dirancang untuk query analitis. Karena itu, dashboard dengan lebih dari seratus juta baris tetap dapat memberikan respons dengan cepat.
  • Redis adalah queue dan cache yang berada di antara web dan worker.
  • MinIO menyediakan object storage yang kompatibel dengan S3 pada server. MinIO menyimpan setiap event mentah yang masuk serta media apa pun yang Anda lampirkan.

Langfuse menerbitkan resource minimum untuk setiap komponen yang dijalankannya. Diagram tersebut menampilkan tiga komponen yang melakukan pekerjaan utama.

GrafikLangfuse published minimum resources per component
Data di balik grafik ini
[
  {
    "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 memori sebesar 8 GiB. Container web dan worker masing-masing membutuhkan 4 GiB. Angka tersebut adalah batas minimum yang dipublikasikan untuk 3 komponen dalam diagram. Halaman yang sama mencantumkan kebutuhan Postgres sebesar 4 GiB, Redis atau Valkey sebesar 1.5 GiB, dan MinIO sebesar 4 GiB. Dengan demikian, kebutuhan minimum keenam komponen berjumlah 25.5 GiB. Panduan Docker Compose resmi project ini merekomendasikan setidaknya 4 core, memori 16 GiB, dan sekitar 100 GiB storage untuk satu mesin. Angka tersebut lebih kecil daripada jumlah kebutuhan minimum setiap komponen. Karena itu, anggap 16 GiB sebagai kebutuhan minimum box Compose bersama, bukan sebagai kapasitas cadangan.

Jangan menjalankan ini pada plan 2 GiB. ClickHouse akan start dan menerima write selama beberapa waktu, lalu berhenti saat menjalankan merge di latar belakang karena proses merge memuat bagian besar tabel ke memori. Anda akan melihat docker compose ps melaporkan container clickhouse sebagai restarting, dmesg memuat baris seperti Out of memory: Killed process 1234 (clickhouse-serv), dan setiap dashboard Langfuse mengembalikan status 500. Dalam kondisi beban yang lebih ringan, ClickHouse akan menolak query dan mencatat DB::Exception: Memory limit (total) exceeded di log. Rencanakan 16 GiB sebagai angka kebutuhannya. Jika VPS yang sama juga akan menjalankan layanan lain, alokasikan resource untuk layanan tersebut secara terpisah karena stack yang relatif ringan seperti workspace AFFiNE yang di-host sendiri tetap membutuhkan gigabyte-nya sendiri, dan ClickHouse tidak akan mengembalikan resource tersebut.

Deploy Langfuse dengan Docker Compose

Klon repositori tersebut. Stack, konfigurasi penghubung, dan environment default semuanya berada di dalam docker-compose.yml.

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

Setiap nilai yang harus diubah ditandai dengan # CHANGEME di 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 persis seperti yang dicetak oleh openssl rand -hex 32. Nilai ini mengenkripsi data sensitif saat tidak sedang digunakan, termasuk key penyedia LLM yang Anda simpan dalam instance. Jika diubah setelah data tersimpan, baris data tersebut tidak dapat lagi didekripsi. Karena itu, perlakukan nilai ini sebagai nilai permanen sejak boot pertama. SALT digunakan untuk melakukan hash pada API key Langfuse. Mengubahnya akan membatalkan semua key yang sudah digunakan oleh agent 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 satunya terlewat, MinIO menolak client tersebut dengan SignatureDoesNotMatch. Pesan ini muncul di log worker, sementara antarmuka web tetap terlihat sehat. Menyimpan nilai-nilai ini dalam file env, bukan dalam file compose yang dilacak, adalah pola yang dibahas di file env dan secret Docker Compose.

Tetapkan tag image sebelum memulai

File bawaan menggunakan docker.langfuse.com/langfuse/langfuse:4 dan docker.langfuse.com/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 belum Anda backup pagi itu. Tetapkan keduanya ke satu release dalam docker-compose.override.yml. Compose menggabungkan file ini di atas file bawaan, sehingga git pull berikutnya tidak menimpa perubahan Anda. Image yang sama dipublikasikan di Docker Hub, dan override di bawah mengambil image tersebut dari sana.

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

Versi 4.3.1 merupakan release 4.3 terbaru pada Agustus 2026. Sejak itu, release baru muncul dengan cepat, dan v4.56.0 merupakan versi terbaru di GitHub pada 11 Oktober 2026. Override di atas menggunakan v4.72.0, versi terbaru di GitHub pada 31 Oktober 2026. Periksa halaman release proyek tersebut di GitHub, tetapkan versi yang berlaku pada hari deployment, lalu ubah nomor itu secara sengaja. Beberapa image penyimpanan dalam file bawaan juga sebaiknya diperlakukan sama karena tag-nya dapat berubah. postgres:17 (nilai default dari variabel POSTGRES_VERSION) dan redis:7 mengikuti versi major. File bawaan kini menggunakan tag versi yang persis untuk docker.io/clickhouse/clickhouse-server, sehingga versi ClickHouse ditetapkan secara spesifik. Aturan ini tidak khusus untuk Langfuse: pelacak latihan openGym yang di-host sendiri menjalankan sebagian kecil dari stack ini, tetapi tetap memerlukan tag git bernama. Apa pun yang memigrasikan databasenya sendiri saat start dapat mengubah pull rutin menjadi perubahan skema.

Jalankan stack tersebut.

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

Boot pertama menjalankan migrasi. Karena itu, tunggu dua atau tiga menit sebelum layanan merespons. Container web mencatat Ready setelah aktif. docker compose ps seharusnya mencantumkan enam service dalam status running. Jika sebuah container terus restart dalam loop, alasannya ada di dalam log container tersebut. Migrasi ClickHouse diterapkan saat container web start. Karena itu, CLICKHOUSE_MIGRATION_URL yang salah muncul di docker compose logs langfuse-web, bukan di log worker yang sedang Anda pantau. Variabel tersebut menggunakan protokol native ClickHouse pada port 9000, bukan port HTTP 8123. Mengarahkannya ke port 8123 membuat migrasi startup container web gagal. Worker menjalankan migrasi background yang lebih lambat, sehingga hasil migrasi tersebut dilaporkan di log worker.

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. Secara default, pemanggilan tersebut tidak memeriksa database. Bentuk failIfDatabaseUnavailable=true adalah endpoint yang sebaiknya dipantau, dan endpoint ini mengembalikan 503 jika database tidak dapat dijangkau. /api/public/ready mengembalikan 200 ketika container web siap menerima trafik, dan 500 setelah container diperintahkan untuk shutdown. Keduanya merupakan pemeriksaan HTTP biasa. Karena itu, halaman status Uptime Kuma dapat memantaunya dan memberi tahu Anda bahwa stack tidak aktif sebelum agent Anda mengetahuinya.

Pasang TLS di depan dan tutup port tambahan

File compose yang disertakan memublikasikan 3000:3000 untuk container web dan 9090:9000 untuk MinIO. Keduanya melakukan bind pada semua interface. Pada IP publik, siapa pun yang memindai port 3000 dapat membuka 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-nya sendiri ke dalam tabel nat. Aturan itu dievaluasi sebelum paket diproses oleh aturan filter ufw, sehingga ufw deny 3000 membiarkan port yang dipublikasikan tetap terbuka. Masalah ini cukup umum sehingga memiliki panduan tersendiri: mengapa port yang dipublikasikan Docker melewati ufw. Lakukan bind ke loopback dalam file override Anda. Gunakan !override dengan Docker Compose 2.24.4 atau yang lebih baru untuk mengganti port yang dipublikasikan. List biasa akan digabungkan dengan binding asli.

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

Selanjutnya, arahkan reverse proxy ke 127.0.0.1:3000 dan biarkan proxy tersebut menangani sertifikat. Untuk Traefik dalam project Compose yang sama, teruskan trafik ke langfuse-web:3000 melalui network Compose menggunakan label yang dijelaskan dalam menjalankan beberapa aplikasi di balik satu reverse proxy Traefik. Caddy melakukan tugas yang sama dengan dua baris jika Langfuse adalah satu-satunya aplikasi pada server. Verifikasi dengan curl -sI https://langfuse.example.com/api/public/ready, lalu pastikan dari mesin kedua bahwa curl http://YOUR_IP:3000 tidak dapat terhubung.

Ada satu hal yang perlu diperhatikan terkait MinIO. Langfuse memberikan URL yang telah ditandatangani sebelumnya dan mengarah ke endpoint S3 tersebut, baik kepada SDK yang mengunggah media maupun kepada browser yang memuatnya. Jika Anda menggunakan trace multimodal yang berisi gambar atau audio, MinIO yang hanya melakukan bind ke loopback membuat lampiran tidak dapat diunggah dari mesin lain atau dimuat di browser. Baca halaman konfigurasi penyimpanan blob sebelum melakukan proxy, karena endpoint yang ditulis ke dalam URL yang telah ditandatangani sebelumnya, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, harus sesuai dengan endpoint yang Anda publikasikan. Trace teks biasa tidak terpengaruh.

Buat akun Anda pada kunjungan pertama, lalu pastikan instance tersebut tetap hanya milik Anda. Tetapkan AUTH_DISABLE_SIGNUP=true setelah akun Anda dibuat, agar orang asing yang membuka halaman tersebut tidak dapat mendaftar sama sekali. Langfuse juga memiliki LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, yang membatasi pihak yang dapat membuat organisasi, tetapi fitur ini hanya tersedia dalam Enterprise Edition dan baru berlaku jika ada license key. Jika Anda sudah menjalankan Authentik sebagai identity provider Anda sendiri, Langfuse menerima koneksi OIDC standar. Dengan demikian, akun 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 pada SDK v4, yang dirilis pada Maret 2026. Kode lama dan panduan lama menggunakan LANGFUSE_HOST. Jika trace masuk ke Langfuse Cloud, bukan ke server Anda, penyebabnya adalah base URL belum diatur karena nilai default mengarah ke instance yang di-host.

Python SDK v5 saat ini memerlukan Python 3.11 atau yang lebih baru serta Langfuse v4.59.0 atau yang lebih baru untuk self-hosting. Versi server yang ditetapkan di atas memenuhi persyaratan tersebut.

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 dikembalikan, lalu menempatkannya 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 menangani pemeriksaan untuk Anda. langfuse.auth_check() mengembalikan False jika key tidak valid atau base URL salah. Dengan begitu, Anda tidak perlu mencari tahu mengapa dashboard kosong. langfuse.flush() menunggu hingga span yang berada dalam antrean terkirim. Fungsi ini diperlukan oleh proses berumur singkat karena SDK mengirimkan batch di latar belakang, sedangkan script yang langsung berhenti akan ikut menghentikan batch yang belum terkirim. Jika seluruh tim mengirim trace, bukan hanya satu script, tetapkan ketiga variabel tersebut satu kali pada gateway yang sudah digunakan semua agent, bukan pada shell masing-masing pengguna. Dengan cara ini, harness OneCLI self-hosted memastikan setiap proses milik rekan kerja tetap terinstrumentasi, sementara key tersimpan di satu tempat.

Mengapa ClickHouse terus bertambah besar?

Trace adalah data yang paling cepat bertambah pada sebagian besar sistem yang di-hosting 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 byte per hari jauh lebih banyak daripada aplikasi yang dipantaunya. Jika dibiarkan, ClickHouse akan memenuhi disk. Disk yang penuh akan menghentikan ingestion, bukan sekadar memperlambatnya.

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

Yang pertama adalah data trace Anda sendiri. Perbaikannya adalah pengaturan retention. Pada instance yang di-hosting sendiri, retensi data merupakan fitur Enterprise Edition dan memerlukan license key. Tanpa license key, Langfuse menyimpan trace, observation, score, dan media tanpa batas waktu. Karena itu, siapkan kapasitas disk untuk kondisi tersebut dan andalkan disk alert di akhir bagian ini. Dengan license, pemilik project dan admin dapat membuka pengaturan project lalu menetapkan periode retensi data dalam satuan hari. Langfuse menerima minimum 3 hari. Selanjutnya, job yang berjalan setiap malam memilih trace, observation, score, dan aset media yang lebih lama daripada periode tersebut, lalu menghapusnya dari ClickHouse dan blob storage, kecuali media yang terkait dengan item dataset yang disimpan. Job tersebut memerlukan izin DeleteObject pada bucket. Kredensial root MinIO dalam file compose default sudah memiliki izin tersebut. Penghapusan bersifat permanen. Karena itu, konfigurasikan ekspor blob storage terlebih dahulu jika Anda memerlukan riwayat jangka panjang. Jangan menulis klausa TTL secara manual pada tabel milik Langfuse. Retention job memastikan ClickHouse dan bucket tetap sinkron, sedangkan TTL manual hanya menghapus salah satu sisi.

Pilih periode berdasarkan cara Anda benar-benar menggunakan data tersebut. Peninjauan biaya dan kualitas biasanya dilakukan pada data berusia beberapa hari, bukan beberapa bulan. Tiga puluh hari merupakan titik awal yang wajar untuk tim kecil. Empat belas hari sudah cukup jika Anda hanya membuka trace ketika terjadi masalah.

Yang kedua adalah tabel system log milik ClickHouse. Hal ini sering mengejutkan pengguna karena disk terus bertambah besar setelah retention dikonfigurasi. ClickHouse menulis trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log, dan latency_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 urutan teratas, nonaktifkan tabel tersebut menggunakan config overlay. ClickHouse menggabungkan setiap file dalam /etc/clickhouse-server/config.d/ ke 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"/>
    <latency_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

Langkah ini menghentikan penulisan baru. Baris yang sudah tersimpan di disk tetap ada. Karena itu, klaim kembali ruang tersebut secara eksplisit dengan DROP TABLE IF EXISTS system.trace_log, dan lakukan hal yang sama untuk setiap tabel yang dihapus. Jika Anda ingin tetap menyimpan data diagnostik, gunakan TTL agresif pada setiap tabel sebagai alternatif untuk remove="1". Dokumentasi scaling Langfuse menjelaskan konfigurasi tersebut. Direktif TTL hanya berlaku saat tabel system pertama kali dibuat. Karena itu, pada instalasi yang sudah ada, dokumentasi yang sama juga menjelaskan cara menerapkan TTL pada tabel tersebut.

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

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

Tambahkan juga alert df -h sederhana pada disk data. Trace tidak bertambah secara bertahap. Ukurannya dapat meningkat 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 kunci API. ClickHouse menyimpan trace. MinIO menyimpan event mentah. Jika hanya Postgres yang dipulihkan, login dapat digunakan tetapi tidak ada riwayat. Jika hanya ClickHouse yang dipulihkan, riwayat tersedia tetapi tidak ada yang dapat login untuk melihatnya. Pemisahan ini bukan hal yang khusus untuk Langfuse. Meja dukungan Chatwoot yang di-host sendiri juga memiliki pola yang sama. Dump Postgres yang dibuat tanpa direktori uploads akan memulihkan percakapan, tetapi semua lampirannya hilang.

Postgres adalah pg_dump biasa, sesuai dengan yang digunakan dalam dokumentasi cadangan Langfuse untuk instalasi Docker.

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

ClickHouse memerlukan perhatian lebih karena direktori data yang sedang aktif dan disalin ketika proses merge berjalan bukan cadangan yang konsisten. Pendekatan sederhana pada satu server 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 prefiks. Dengan demikian, clone di direktori bernama langfuse menghasilkan langfuse_langfuse_clickhouse_data. Jika salah, docker run membuat volume kosong baru tanpa menampilkan error, dan arsip Anda tidak berisi apa pun.

Langfuse mengunggah data event mentah ke bucket pada setiap permintaan ingestion dan membacanya kembali untuk mencoba ulang job ingestion yang gagal. Karena itu, penghentian singkat ClickHouse terutama menyebabkan worker mencoba ulang setelahnya. Lakukan pada jam dengan aktivitas rendah dan batasi durasinya. Untuk instance yang lebih sibuk, pernyataan BACKUP DATABASE default TO S3(...) milik ClickHouse sendiri dapat menulis cadangan yang konsisten tanpa menghentikan server. MinIO adalah bagian ketiga. mc mirror atau replikasi MinIO ke bucket di luar server dapat digunakan untuk mencadangkannya. Apa pun yang Anda hasilkan, simpan cadangan tersebut di luar server. Itulah fungsi cadangan restic terenkripsi pada VPS.

Redis menyimpan antrean dan cache. Jika Redis hilang, job yang masih berada dalam antrean ikut hilang, meskipun file event mentahnya masih ada di bucket.

Catatan tentang konsistensi ini penting dan harus dijelaskan dengan jelas. Postgres dan ClickHouse dibuat dump pada waktu yang berbeda. Akibatnya, pemulihan dapat menghasilkan baris proyek tanpa trace, atau trace untuk proyek yang sudah tidak ada. Langfuse dapat menangani kondisi tersebut, tetapi buat kedua dump dalam waktu yang berdekatan dan pada periode dengan trafik rendah. Bucket event adalah perlindungan utama karena Langfuse mengunggah data event mentah ke sana pada setiap permintaan ingestion.

Pulihkan cadangan ke scratch stack setidaknya sekali. Dengan cara ini, 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 kebutuhan memori Langfuse yang di-hosting sendiri?

Siapkan 4 core CPU dan memori 16 GiB. Jumlah ini direkomendasikan oleh panduan Langfuse Docker Compose untuk satu mesin virtual, ditambah sekitar 100 GiB penyimpanan. Minimum yang dipublikasikan untuk komponennya adalah 8 GiB untuk ClickHouse dan masing-masing 4 GiB untuk container web dan worker. Halaman yang sama mencantumkan 4 GiB untuk Postgres, 1.5 GiB untuk Redis, dan 4 GiB untuk MinIO. Dengan demikian, keenam komponen tersebut membutuhkan total 25.5 GiB, lebih besar daripada rekomendasi Compose sebesar 16 GiB.

Mengapa disk ClickHouse terus penuh setelah saya menetapkan retensi data?

Pengaturan retensi hanya mencakup data milik Langfuse. ClickHouse menulis tabel diagnostik trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log, dan latency_log secara terpisah. Tabel tersebut tidak memiliki TTL secara bawaan. 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, dan hapus tabel yang sudah ada untuk mengembalikan ruang yang telah digunakan.

Berapa periode retensi data minimum di Langfuse?

Tiga hari. Retensi ditetapkan per proyek dalam pengaturan proyek atau melalui Organization Management API. Pekerjaan terjadwal setiap malam menghapus traces, observations, scores, dan media assets yang lebih lama daripada periode tersebut dari ClickHouse dan blob storage, kecuali media yang terkait dengan item dataset tersimpan. Pada instance yang di-hosting sendiri, fitur ini tersedia dalam Enterprise Edition dan memerlukan license key. Tanpa license key, data disimpan tanpa batas waktu. Penghapusan tidak dapat dibatalkan. Karena itu, konfigurasikan ekspor ke blob storage terlebih dahulu jika Anda memerlukan riwayat yang lebih lama daripada periode tersebut.

Apakah saya harus mencadangkan Postgres dan ClickHouse?

Ya, karena keduanya menyimpan data yang berbeda. Postgres menyimpan pengguna, organisasi, proyek, dan API keys. ClickHouse menyimpan data trace itu sendiri. Pemulihan hanya dari cadangan Postgres menghasilkan instance yang dapat Anda gunakan untuk login, tetapi tidak memiliki data lain. Cadangkan juga bucket MinIO karena bucket tersebut menyimpan raw events yang dipertahankan 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 terbarunya dibangun di atas OpenTelemetry. Instrumentasi OTel untuk Anthropic dan OpenAI dapat mengekspor data langsung ke Langfuse. Di Python, jalankan pip install langfuse opentelemetry-instrumentation-anthropic, panggil AnthropicInstrumentor().instrument() satu kali 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 tersedia.

Apakah artikel ini bermanfaat?