Cara Self-host Langfuse untuk Ejen AI di VPS

Mengapa perlu menjejak ejen AI

Anda mengehos sendiri Langfuse untuk melihat perkara yang sebenarnya dilakukan oleh ejen anda semasa satu larian. Langfuse ialah alat kebolehcerapan LLM (model bahasa besar) sumber terbuka. Ia merekodkan setiap prompt, setiap respons model, setiap panggilan alat dan setiap token, kemudian mengumpulkannya di bawah satu jejak yang boleh anda buka dan baca. Menjalankannya pada VPS anda sendiri bermakna prompt tersebut tidak pernah meninggalkan pelayan yang anda kawal.

Sebab untuk melakukannya adalah jelas. Anda tidak boleh membaiki masalah kos atau masalah kualiti yang tidak dapat anda lihat. Invois pembekal memberitahu anda bahawa hari Selasa menelan kos empat kali ganda berbanding hari Isnin. Satu jejak memberitahu anda larian ejen yang mana menyebabkannya, prompt yang mana berkembang sehingga 40,000 token, dan gelung cuba semula yang mana berjalan sebanyak sembilan kali sebelum berhenti. Invois memberikan anda nombor tersebut. Jejak memberikan anda kod yang menghasilkannya.

Tiga istilah digunakan sepanjang panduan ini. Jejak (trace) ialah satu larian hujung-ke-hujung ejen anda. Pemerhatian (observation) ialah satu langkah di dalam larian tersebut: span untuk kod biasa, generasi untuk panggilan kepada model. Skor (score) ialah nombor yang dilampirkan pada satu jejak, daripada semakan manusia atau penilai automatik. Langfuse menggunakan OpenTelemetry (OTel), piawaian neutral vendor untuk penjejakan teragih, jadi instrumentasi yang anda miliki sudah boleh dihalakan kepadanya.

Apakah yang sebenarnya dijalankan oleh Langfuse untuk self-hosting

Langfuse v4 bukan sekadar satu kontena. Ia terdiri daripada dua kontena aplikasi dan empat servis storan, dan pada satu VPS, kesemua enam komponen ini berjalan pada pelayan anda.

• langfuse-web menyediakan antara muka web dan API ingestion.
• langfuse-worker mengosongkan baris gilir di latar belakang. Ia menghuraikan kelompok ingestion, mengira kos, dan menjalankan tugasan pengekalan data (retention job) pada waktu malam.
• Postgres menyimpan data transaksi seperti pengguna, organisasi, projek, API keys dan prompt.
• ClickHouse menyimpan data trace itu sendiri, iaitu pemerhatian (observations) dan skor. Ia merupakan storan lajur (column store) yang dibina untuk pertanyaan analitikal, sebab itulah papan pemuka (dashboard) yang memaparkan ratusan juta baris data masih boleh memberikan respons dengan pantas.
• Redis berfungsi sebagai baris gilir dan cache yang terletak di antara web dan worker.
• MinIO menyediakan storan objek yang serasi dengan S3 pada pelayan anda. Ia menyimpan setiap peristiwa mentah yang masuk serta sebarang media yang anda lampirkan.

Langfuse menerbitkan keperluan sumber minimum bagi tiga komponen yang melakukan kerja tersebut.

[
  {
    "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 sahaja memerlukan 8 GiB memori. Kontena web dan worker masing-masing memerlukan 4 GiB. Itu adalah had minimum yang diterbitkan untuk 3 komponen yang disaizkan oleh Langfuse, manakala Postgres, Redis dan MinIO masih memerlukan memori tambahan. Panduan Docker Compose projek itu sendiri mengesyorkan mesin dengan 4 teras, 16 GiB memori dan sekitar 100 GiB storan, yang sepadan dengan pengiraan tersebut dan bukannya sekadar anggaran kasar.

Jangan cuba jalankan ini pada pelan 2 GiB. ClickHouse akan bermula, menerima data untuk seketika, kemudian terhenti semasa proses penggabungan latar belakang (background merge), kerana proses penggabungan memuatkan sebahagian besar jadual ke dalam memori. Anda akan melihat docker compose ps melaporkan kontena clickhouse sebagai restarting, dmesg mengandungi baris seperti Out of memory: Killed process 1234 (clickhouse-serv), dan setiap papan pemuka Langfuse akan memaparkan ralat 500. Di bawah tekanan yang lebih ringan, ClickHouse akan menolak pertanyaan tersebut dan mencatatkan DB::Exception: Memory limit (total) exceeded dalam log. Lapan GiB boleh digunakan untuk seorang pembangun yang menghantar beberapa ribu trace sehari. Enam belas GiB adalah jumlah yang perlu dirancang.

Melancarkan Langfuse dengan Docker Compose

Klon repositori tersebut. Stak, pendawaian, dan persekitaran lalai semuanya terkandung dalam docker-compose.yml miliknya.

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

Setiap nilai yang perlu anda ubah ditandakan sebagai # CHANGEME dalam fail tersebut. Jana tiga rahsia aplikasi terlebih dahulu.

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

ENCRYPTION_KEY mestilah 256 bit yang ditulis sebagai 64 aksara heksadesimal, iaitu tepat seperti yang dicetak oleh openssl rand -hex 32. Ia menyulitkan nilai sensitif semasa dalam storan, termasuk mana-mana kunci pembekal LLM yang anda simpan dalam instans tersebut. Mengubahnya selepas data wujud akan menyebabkan baris tersebut tidak lagi boleh dinyahsulit, jadi anggap ia sebagai kekal sejak but pertama. SALT digunakan untuk melakukan hashing pada kunci API Langfuse anda, jadi mengubahnya akan membatalkan setiap kunci yang sedang digunakan oleh ejen anda.

Kemudian, tetapkan POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH, dan MINIO_ROOT_PASSWORD. Kata laluan MinIO muncul di empat tempat: sekali sebagai MINIO_ROOT_PASSWORD, kemudian sekali lagi sebagai LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY, dan LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Jika terlepas satu, MinIO akan menolak klien tersebut dengan SignatureDoesNotMatch, yang akan muncul dalam log pekerja sementara antara muka web masih kelihatan sihat. Mengekalkan nilai-nilai ini dalam fail env dan bukannya dalam fail compose yang dijejak adalah corak yang dibincangkan dalam fail env dan rahsia Docker Compose.

Tetapkan tag imej sebelum anda bermula

Fail yang dibekalkan menggunakan langfuse/langfuse:4 dan langfuse/langfuse-worker:4. Tag tersebut sentiasa berubah. Langfuse menjalankan migrasi Postgres dan ClickHouse secara automatik semasa permulaan, jadi docker compose pull rutin beberapa bulan kemudian akan menjadi migrasi skema yang tidak dirancang pada pangkalan data yang tidak anda sandarkan pada pagi itu. Tetapkan kedua-duanya kepada satu keluaran dalam docker-compose.override.yml, yang akan digabungkan oleh Compose di atas fail yang dibekalkan supaya git pull kemudian tidak akan bercanggah dengan suntingan anda.

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

Versi 4.3.1 merupakan keluaran 4.3 semasa pada Ogos 2026 (4.4.0 telah dikeluarkan sejak itu). Semak halaman keluaran GitHub projek tersebut, tetapkan apa sahaja yang terkini pada hari anda melancarkan, kemudian ubah nombor tersebut secara sengaja. Imej storan dalam fail yang dibekalkan sudah ditetapkan kepada versi major, postgres:17, clickhouse-server:25.12, dan redis:7, dan ia wajar menerima layanan yang sama.

Lancarkan ia.

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

But pertama akan menjalankan migrasi, jadi berikan seminit atau dua minit sebelum sebarang tindak balas diberikan. docker compose ps sepatutnya menyenaraikan enam servis dalam status running. Jika pekerja dimulakan semula secara berulang, lognya mengandungi puncanya: CLICKHOUSE_MIGRATION_URL menggunakan protokol asli ClickHouse pada port 9000, bukan port HTTP 8123, dan menghalakannya ke 8123 akan gagal di situ sementara kontena web masih kelihatan baik.

Semak kesihatan daripada pelayan 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

Panggilan /api/public/health biasa hanya membuktikan proses API masih hidup, kerana ia sengaja melangkau pangkalan data supaya servis terus beroperasi semasa Postgres mengalami gangguan seketika. Bentuk failIfDatabaseUnavailable=true adalah yang wajar dipantau, dan ia akan mengembalikan 503 apabila pangkalan data tidak dapat dicapai. /api/public/ready mengembalikan 200 sebaik sahaja migrasi selesai dan kontena sedia menerima trafik. Kedua-duanya adalah semakan HTTP biasa, jadi halaman status Uptime Kuma boleh memantau dan memberitahu anda bahawa stak tersebut tidak berfungsi sebelum ejen anda menyedarinya.

Letakkan TLS di hadapan dan tutup port tambahan

Fail compose yang dibekalkan menerbitkan 3000:3000 untuk kontena web dan 9090:9000 untuk MinIO. Kedua-duanya terikat pada setiap antara muka. Pada IP awam, ini bermakna sesiapa sahaja yang mengimbas port 3000 akan sampai ke halaman pendaftaran anda, dan sesiapa yang mengimbas 9090 akan berhubung dengan bucket yang menyimpan prompt mentah anda.

Peraturan firewall sahaja tidak menutup port tersebut. Docker menulis peraturan DNAT sendiri ke dalam jadual nat, dan peraturan tersebut dinilai sebelum peraturan penapis ufw melihat paket itu, jadi ufw deny 3000 membiarkan port yang diterbitkan terbuka. Perkara ini cukup kerap berlaku sehingga mempunyai panduan tersendiri: mengapa port yang diterbitkan Docker memintas ufw. Sebaliknya, ikat pada loopback dalam fail 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 mestilah alamat awam yang tepat termasuk skema, kerana aliran log masuk membina URL panggil balik (callback URL) daripada nilai tersebut. Biarkan ia sebagai http://localhost:3000 di sebalik proksi HTTPS dan pusingan log masuk akan menghantar pelayar ke tempat yang tidak boleh dicapai.

Sekarang, halakan reverse proxy ke 127.0.0.1:3000 dan biarkan ia memegang sijil tersebut. Traefik dalam projek Compose yang sama adalah pilihan biasa, dan label penghalaan adalah label yang dibincangkan dalam menjalankan beberapa aplikasi di sebalik satu reverse proxy Traefik. Caddy melakukan tugas yang sama dalam dua baris jika Langfuse adalah satu-satunya aplikasi pada pelayan tersebut. Sahkan dengan curl -sI https://langfuse.example.com/api/public/ready, kemudian pastikan dari mesin kedua bahawa curl http://YOUR_IP:3000 kini tamat masa (times out).

Satu peringatan mengenai MinIO. Langfuse menghidangkan media yang dilampirkan kepada pelayar anda melalui URL pra-tandatangan (presigned URLs) yang menghala ke endpoint S3 tersebut, jadi jika anda menggunakan trace berbilang mod yang membawa imej atau audio, MinIO yang hanya terikat pada loopback bermakna lampiran tersebut tidak akan dimuatkan. Baca halaman konfigurasi storan blob sebelum melakukan proksi ke atasnya, kerana endpoint yang ditulis ke dalam URL pra-tandatangan perlu sepadan dengan apa yang anda terbitkan. Trace teks biasa tidak terjejas.

Cipta akaun anda pada lawatan pertama, kemudian pastikan instance tersebut kekal milik anda. Tetapkan LANGFUSE_ALLOWED_ORGANIZATION_CREATORS kepada alamat e-mel anda sendiri, supaya orang asing yang sampai ke halaman tersebut tidak boleh mencipta organisasi pada pelayan anda. Jika anda sudah menjalankan Authentik sebagai penyedia identiti anda sendiri, Langfuse menerima sambungan OIDC standard, jadi akaun akan diuruskan bersama aplikasi anda yang lain dan bukannya tersimpan dalam senarai kata laluan yang hanya diketahui oleh pelayan ini.

Hantar trace pertama anda

Cipta projek dalam antara muka web dan salin kunci awam serta kunci rahsia daripada tetapan projek. Python SDK membaca tiga pemboleh ubah persekitaran.

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

LANGFUSE_BASE_URL ialah nama pemboleh ubah dalam SDK v4, yang dikeluarkan pada Mac 2026. Kod lama dan panduan lama menggunakan LANGFUSE_HOST. Jika trace anda mendarat di Langfuse Cloud dan bukannya pelayan anda, punca masalahnya ialah base URL yang tidak ditetapkan, kerana lalai (default) menghala ke instans yang dihoskan.

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

Dekorator @observe membuka pemerhatian (observation) di sekeliling fungsi, menangkap argumen dan nilai pulangannya, serta menyarangnya di bawah mana-mana pemerhatian yang sedang aktif. AnthropicInstrumentor ialah instrumentasi OpenTelemetry untuk klien Anthropic, dan ia menukarkan setiap panggilan messages.create menjadi penjanaan yang membawa nama model, penggunaan token dan kependaman (latency), tanpa sebarang perubahan pada tapak panggilan.

Dua panggilan melakukan penyemakan untuk anda. langfuse.auth_check() mengembalikan False jika kunci tidak sah atau base URL salah, yang lebih pantas daripada tertanya-tanya mengapa papan pemuka kosong. langfuse.flush() menyekat (block) sehingga span yang beratur dihantar, dan proses yang berjalan singkat memerlukannya, kerana SDK melakukan batch di latar belakang dan skrip yang tamat serta-merta akan membawa batch yang belum dihantar bersamanya.

Mengapa penggunaan storan ClickHouse terus meningkat?

Trace merupakan data yang paling cepat berkembang bagi kebanyakan pengguna yang menguruskan pelayan sendiri. Setiap pelaksanaan ejen menulis satu baris bagi setiap langkah, dan input serta output disimpan sepenuhnya. Oleh itu, ejen yang aktif dengan prompt yang panjang menghasilkan jumlah bait yang jauh lebih besar setiap hari berbanding aplikasi yang dipantaunya. Jika dibiarkan, ClickHouse akan memenuhi cakera, dan cakera yang penuh akan menghentikan proses penyerapan data (ingestion) dan bukannya sekadar melambatkannya.

Terdapat dua perkara berasingan yang menyebabkan pertumbuhan ini, dan kedua-duanya memerlukan penyelesaian yang berbeza.

Perkara pertama ialah data trace anda sendiri, dan penyelesaiannya ialah tetapan pengekalan (retention). Buka tetapan projek dalam antara muka web dan tetapkan tempoh pengekalan data dalam hari. Langfuse menerima tempoh minimum 3 hari. Satu tugasan harian (nightly job) kemudiannya akan memilih trace, pemerhatian, skor dan aset media yang lebih lama daripada tempoh tersebut lalu memadamkannya daripada ClickHouse dan storan blob. Tugasan ini memerlukan kebenaran DeleteObject pada bucket, yang sudah pun dimiliki oleh kelayakan root MinIO dalam fail compose lalai. Pemadaman adalah kekal, jadi konfigurasikan eksport storan blob terlebih dahulu jika anda memerlukan sejarah jangka panjang. Jangan tulis klausa TTL secara manual pada jadual milik Langfuse: tugasan pengekalan itulah yang memastikan ClickHouse dan bucket selari, manakala TTL manual hanya memadamkan satu bahagian sahaja.

Pilih tempoh berdasarkan penggunaan sebenar anda. Kajian kos dan kualiti biasanya dilakukan pada data yang berusia beberapa hari, bukan berbulan-bulan. 30 hari adalah permulaan yang munasabah untuk pasukan kecil, dan 14 hari sudah memadai jika anda hanya membuka trace apabila berlaku kerosakan.

Perkara kedua ialah jadual log sistem ClickHouse itu sendiri, dan ini sering mengejutkan pengguna kerana cakera terus penuh walaupun pengekalan telah dikonfigurasikan. ClickHouse menulis trace_log, text_log, opentelemetry_span_log, metric_log dan asynchronous_metric_log untuk diagnostik dalamannya sendiri; ia dihantar tanpa TTL, dan Langfuse tidak pernah membacanya. Cari dahulu ke mana perginya ruang cakera anda.

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
)

Jalankannya dengan docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Jika jadual sistem berada di kedudukan teratas, matikannya dengan overlay konfigurasi, kerana ClickHouse menggabungkan setiap fail dalam /etc/clickhouse-server/config.d/ ke atas konfigurasi utamanya semasa permulaan.

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

Lekapkan (mount) fail tersebut dan mulakan semula ClickHouse.

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

Tindakan itu menghentikan penulisan baharu. Baris yang sudah ada pada cakera akan kekal di sana, jadi tuntut semula ruang tersebut secara eksplisit dengan DROP TABLE IF EXISTS system.trace_log dan lakukan perkara yang sama untuk setiap jadual yang anda alihkan. Jika anda lebih suka menyimpan diagnostik tersebut, alternatifnya ialah menetapkan TTL yang agresif pada setiap jadual dan bukannya remove="1", seperti yang diperincikan dalam dokumentasi penskalaan Langfuse.

Satu lagi jadual yang perlu diketahui ialah blob_storage_file_log. Jadual ini menjejaki fail acara yang dimuat naik ke bucket anda. Jika anda juga menetapkan polisi kitaran hayat (lifecycle policy) pada bucket tersebut, berikan jadual itu TTL yang sepadan supaya kedua-duanya tidak terkeluar daripada penyelarasan.

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

Letakkan amaran df -h yang ringkas pada cakera data juga. Trace tidak berkembang secara sekata. Ia berkembang pada hari anda melancarkan ejen baharu, dan tanda pertama perkara ini berlaku tidak sepatutnya adalah kegagalan proses penyerapan data.

Sandarkan Postgres dan ClickHouse

Sandaran Langfuse terdiri daripada tiga bahagian. Postgres menyimpan pengguna, organisasi, projek dan kunci API anda. ClickHouse menyimpan jejak (traces). MinIO menyimpan peristiwa mentah. Jika anda memulihkan Postgres sahaja, anda akan mendapat log masuk yang berfungsi tetapi tanpa sejarah. Jika anda memulihkan ClickHouse sahaja, anda akan mendapat sejarah tetapi tiada sesiapa boleh log masuk untuk melihatnya.

Postgres ialah pg_dump biasa, yang merupakan kaedah yang disyorkan oleh dokumentasi sandaran Langfuse.

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

ClickHouse memerlukan perhatian lebih, kerana direktori data yang disalin semasa proses penggabungan (merges) sedang berjalan tidak akan menghasilkan sandaran yang konsisten. Pendekatan mudah pada satu pelayan adalah dengan menghentikan kontena dan mengarkibkan volum tersebut.

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 volum yang dipaparkan oleh docker volume ls, bukan nama yang tertulis dalam YAML. Fail tersebut mengisytiharkan langfuse_clickhouse_data, dan Compose meletakkan awalan nama projek padanya, jadi klon dalam direktori bernama langfuse akan menghasilkan langfuse_langfuse_clickhouse_data. Jika anda tersilap, docker run akan mencipta volum kosong yang baharu tanpa sebarang amaran, dan arkib anda tidak akan mengandungi apa-apa.

Kontena web menulis setiap peristiwa masuk ke dalam bucket sebelum pekerja (worker) memprosesnya, jadi penghentian ClickHouse yang singkat biasanya bermakna pekerja akan mencuba semula selepas itu. Lakukan ini pada waktu trafik rendah dan pastikan ia singkat. Bagi instans yang lebih sibuk, pernyataan BACKUP DATABASE default TO S3(...) milik ClickHouse sendiri akan menulis sandaran yang konsisten tanpa perlu menghentikan pelayan. MinIO adalah bahagian ketiga, dan mc mirror atau replikasi MinIO ke bucket di luar pelayan dapat melindunginya. Apa sahaja yang anda hasilkan, pindahkan ia keluar dari pelayan, itulah tujuan sandaran restic terenkripsi pada VPS.

Redis tidak memerlukan sandaran. Ia menyimpan baris gilir dan cache, jadi kehilangannya hanya menyebabkan kehilangan peristiwa yang sedang diproses dan tiada data lama yang terjejas.

Amaran tentang konsistensi adalah nyata dan perlu dinyatakan dengan jelas. Postgres dan ClickHouse disandarkan pada waktu yang berbeza, jadi pemulihan boleh menyebabkan baris projek wujud tanpa jejak, atau jejak wujud bagi projek yang sudah tiada. Langfuse boleh bertoleransi dengan perkara ini, tetapi lakukan kedua-dua sandaran tersebut secara berdekatan dan dalam waktu trafik rendah. Bucket peristiwa adalah jaring keselamatan sebenar, kerana Langfuse mengekalkan setiap peristiwa masuk di sana sebelum memprosesnya.

Lakukan pemulihan ke dalam stack percubaan sekurang-kurangnya sekali. Itulah cara untuk mengetahui tentang kesilapan nama volum sekarang, bukannya semasa gangguan perkhidmatan berlaku.

Perkara yang perlu dilihat terlebih dahulu

Empat perkara ini wajar diberi perhatian pada minggu pertama.

• Kos setiap trace. Langfuse mengira kos berdasarkan nama model dan penggunaan token, jadi susun trace mengikut kos dan baca trace yang paling mahal dari awal hingga akhir. Jawapannya biasanya berpunca daripada prompt yang semakin panjang: keseluruhan dokumen yang ditampal ke dalam konteks, atau sejarah perbualan yang tidak dipotong. Sebaik sahaja anda dapat melihatnya, mengawal kos ejen AI anda menjadi satu tugasan kejuruteraan dan bukannya sekadar tekaan.
• Pecahan penggunaan token mengikut input dan output. Token input adalah banyak dan murah, token output adalah sedikit dan mahal, manakala input yang dicache adalah lebih murah lagi. Perakaunan yang sama dihuraikan dalam cara penggunaan token Claude Code dikira, dan ia terpakai untuk mana-mana ejen yang anda tulis sendiri.
• Persentil kependaman (latency). Nilai median menyembunyikan masalah sebenar. p95 dan p99 adalah tempat berlakunya timeout, dan di dalam gelung ejen, panggilan alat yang perlahan pada p95 akan didarabkan dengan bilangan lelaran.
• Panggilan alat yang gagal. Tapis pemerhatian mengikut tahap ERROR. Alat yang gagal sebanyak 5% daripada masa tidak kelihatan dalam kadar kejayaan agregat, tetapi sangat jelas dalam trace, di mana anda dapat melihat model mencuba semula dan kemudian membazirkan token untuk mencari jalan penyelesaian.

Tetapkan tempoh pengekalan data dan pilih papan pemuka yang akan anda semak setiap minggu pada hari yang sama anda melakukan deployment. Alat kebolehcerapan (observability) yang tidak dibuka oleh sesiapa hanyalah pangkalan data yang memenuhi ruang cakera.

FAQ

Berapakah memori yang diperlukan oleh Langfuse yang dihoskan sendiri?

Rancang untuk 4 teras CPU dan 16 GiB memori, iaitu saranan panduan Docker Compose Langfuse untuk satu mesin maya, ditambah sekitar 100 GiB storan. Minimum komponen yang diterbitkan ialah 8 GiB untuk ClickHouse dan 4 GiB setiap satu untuk kontena web dan worker, manakala Postgres, Redis dan MinIO masih memerlukan memori tambahan. Lapan GiB boleh menjalankan satu instans pembangun. Dua GiB tidak mencukupi: ClickHouse akan ditamatkan oleh kernel semasa proses penggabungan latar belakang, dan dmesg menunjukkan Out of memory: Killed process.

Mengapakah cakera ClickHouse saya terus penuh selepas saya menetapkan pengekalan data?

Tetapan pengekalan hanya meliputi data Langfuse sendiri. ClickHouse secara berasingan menulis jadual diagnostiknya trace_log, text_log, opentelemetry_span_log, metric_log dan asynchronous_metric_log, dan jadual tersebut dihantar tanpa TTL. Jalankan pertanyaan system.parts yang dikumpulkan mengikut jadual untuk melihat yang mana paling besar, kemudian nyahdayakan jadual yang tidak digunakan dengan entri remove="1" dalam fail di bawah /etc/clickhouse-server/config.d/, mulakan semula ClickHouse, dan gugurkan jadual sedia ada untuk menuntut semula ruang yang telah digunakan.

Berapakah tempoh pengekalan data minimum dalam Langfuse?

Tiga hari. Pengekalan ditetapkan bagi setiap projek dalam tetapan projek, atau melalui API projek, dan tugas malam akan memadamkan jejak, pemerhatian, skor dan aset media yang lebih lama daripada tempoh tersebut daripada ClickHouse dan storan blob. Pemadaman tidak boleh dibatalkan, jadi konfigurasikan eksport storan blob terlebih dahulu jika anda memerlukan sejarah melebihi tempoh tersebut.

Adakah saya perlu membuat sandaran untuk Postgres dan ClickHouse?

Ya, kerana kedua-duanya menyimpan maklumat yang berbeza. Postgres menyimpan pengguna, organisasi, projek dan kunci API, manakala ClickHouse menyimpan data jejak itu sendiri. Pemulihan Postgres sahaja akan memberikan anda instans yang boleh dilog masuk tetapi kosong. Buat sandaran baldi MinIO juga, kerana ia menyimpan peristiwa mentah yang dikekalkan oleh Langfuse semasa ketibaan, yang merupakan perkara paling hampir dengan sumber kebenaran dalam tindanan tersebut.

Bolehkah saya menghalakan persediaan OpenTelemetry sedia ada ke Langfuse yang dihoskan sendiri?

Boleh. Langfuse v4 dan SDK v4 miliknya dibina berasaskan OpenTelemetry, dan instrumentasi OTel Anthropic serta OpenAI mengeksport terus kepadanya. Dalam Python, jalankan pip install langfuse opentelemetry-instrumentation-anthropic, panggil AnthropicInstrumentor().instrument() sekali semasa permulaan, dan tetapkan LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY dan LANGFUSE_BASE_URL kepada hos anda sendiri. Sahkan dengan langfuse.auth_check() sebelum mencari papan pemuka yang hilang.