Jinsi ya kujiendeshea Langfuse kwenye VPS yako

Kwa nini ufuatilie wakala wa AI hata kidogo

Unajiendeshea Langfuse ili kuona kile ambacho wakala wako alifanya kweli wakati wa utekelezaji. Langfuse ni zana huria ya ufuatiliaji wa LLM (large language model). Inarekodi kila prompt, kila jibu la model, kila wito wa tool na kila token, kisha inavikusanya chini ya trace moja unayoweza kuifungua na kuisoma. Kuiendesha kwenye VPS yako mwenyewe inamaanisha kuwa prompts hizo hazitoki kamwe kwenye seva unayoimiliki.

Sababu ya kuhangaika nayo iko wazi. Huwezi kurekebisha tatizo la gharama au tatizo la ubora ambalo huwezi kuliona. Ankara ya mtoa huduma inakuambia kuwa Jumanne iligharimu mara nne zaidi ya Jumatatu. Trace inakuambia ni utekelezaji upi wa wakala uliofanya hivyo, ni prompt ipi iliyokua hadi kufikia 40,000 tokens, na ni retry loop ipi iliyokimbia mara tisa kabla ya kukata tamaa. Ankara inakupa namba. Trace inakupa msimbo uliotengeneza namba hiyo.

Istilahi tatu zinatumika katika mwongozo huu wote. Trace ni utekelezaji mmoja wa mwanzo hadi mwisho wa wakala wako. Observation ni hatua moja ndani ya utekelezaji huo: span kwa msimbo wa kawaida, generation kwa wito wa kwenda kwenye model. Score ni namba iliyoambatishwa kwenye trace, kutoka kwa ukaguzi wa binadamu au tathmini ya kiotomatiki. Langfuse inatumia OpenTelemetry (OTel), kiwango kisichoegemea upande wowote kwa ajili ya distributed tracing, kwa hivyo instrumentation uliyonayo tayari inaweza kuielekeza huko.

Kile ambacho self-hosting ya Langfuse inakiendesha kihalisi

Langfuse v4 si container moja. Ni container mbili za programu na huduma nne za hifadhi, na kwenye VPS moja, zote sita huendeshwa kwenye mashine yako.

• langfuse-web inahudumia kiolesura cha wavuti na API ya ingestion.
• langfuse-worker inafuta foleni (queue) kwa nyuma. Inachakata batches za ingestion, inahesabu gharama, na kuendesha kazi ya retention ya kila usiku.
• Postgres inahifadhi data za miamala kama watumiaji, mashirika, miradi, API keys na prompts.
• ClickHouse inahifadhi data za trace zenyewe, yaani observations na scores. Hii ni column store iliyoundwa kwa ajili ya queries za uchambuzi, ndiyo maana dashibodi inayochakata mamilioni ya safu (rows) bado inajibu haraka.
• Redis ni foleni na cache iliyopo kati ya wavuti na worker.
• MinIO inakupa hifadhi ya vitu (object storage) inayooana na S3 kwenye mashine yako. Inahifadhi kila tukio (event) linaloingia pamoja na media yoyote unayoiambatanisha.

Langfuse inachapisha rasilimali za chini kabisa zinazohitajika kwa vipengele vitatu vinavyofanya kazi.

[
  {
    "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 pekee inahitaji 8 GiB ya kumbukumbu. Container ya wavuti na worker kila moja inahitaji 4 GiB. Hizo ndizo viwango vya chini vilivyochapishwa kwa vipengele 3 ambavyo Langfuse inavihitaji, na Postgres, Redis pamoja na MinIO bado zinahitaji kumbukumbu ya ziada juu ya hiyo. Mwongozo wa Docker Compose wa mradi huu unapendekeza mashine yenye cores 4 na 16 GiB ya kumbukumbu na takriban 100 GiB ya hifadhi, ambayo inalingana na hesabu hiyo badala ya kuongeza ziada isiyo ya lazima.

Usijaribu kuendesha hii kwenye mpango wa 2 GiB. ClickHouse itaanza, itakubali data kwa muda, kisha itakufa wakati wa background merge, kwa sababu merge hupakia sehemu kubwa za jedwali kwenye kumbukumbu. Utaona docker compose ps ikiripoti container ya clickhouse kama restarting, dmesg ikiwa na mstari kama Out of memory: Killed process 1234 (clickhouse-serv), na kila dashibodi ya Langfuse ikirejesha 500. Chini ya shinikizo dogo, ClickHouse inakataa query na kuandika kwenye log DB::Exception: Memory limit (total) exceeded. Nane GiB inaweza kufanya kazi kwa msanidi mmoja anayetuma maelfu machache ya traces kwa siku. Kumi na sita ndiyo idadi unayopaswa kuipangia.

Deploy Langfuse kwa kutumia Docker Compose

Clone repository hiyo. Stack, muunganisho, na mazingira ya awali yote yanapatikana ndani ya docker-compose.yml yake.

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

Kila thamani unayopaswa kubadilisha imewekwa alama ya # CHANGEME kwenye faili hilo. Tengeneza siri tatu za programu kwanza.

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

ENCRYPTION_KEY lazima iwe na bits 256 zilizoandikwa kama herufi 64 za hex, ambazo ndizo hasa openssl rand -hex 32 inazochapisha. Inaficha thamani nyeti zilizohifadhiwa, ikiwemo funguo zozote za mtoa huduma wa LLM unazohifadhi kwenye instance hiyo. Ukiibadilisha baada ya data kuwepo, safu hizo hazitaweza kusomeka tena, kwa hivyo ichukulie kama ya kudumu tangu boot ya kwanza. SALT inatumika kuhash funguo zako za Langfuse API, kwa hivyo kuibadilisha kutafuta kila ufunguo ambao mawakala wako wanautumia sasa.

Kisha weka POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH na MINIO_ROOT_PASSWORD. Nenosiri la MinIO linaonekana katika sehemu nne: mara moja kama MINIO_ROOT_PASSWORD, kisha tena kama LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY na LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Ukikosa moja, MinIO itakataa mteja huyo kwa SignatureDoesNotMatch, ambayo inaishia kwenye log ya worker wakati interface ya wavuti bado inaonekana kuwa sawa. Kuweka thamani hizi kwenye faili la env badala ya faili la compose linalofuatiliwa ni utaratibu unaoelezewa katika faili za Docker Compose env na siri.

Funga tag za image kabla ya kuanza

Faili lililotolewa linatumia langfuse/langfuse:4 na langfuse/langfuse-worker:4. Tag hizo hubadilika. Langfuse huendesha migrations zake za Postgres na ClickHouse kiotomatiki wakati wa kuanza, kwa hivyo docker compose pull ya kawaida miezi baadaye inakuwa migration ya schema isiyopangwa kwenye database ambayo hukui-backup asubuhi hiyo. Funga zote mbili kwenye toleo moja katika docker-compose.override.yml, ambayo Compose huiunganisha juu ya faili lililotolewa ili git pull ya baadaye isigongane na marekebisho yako.

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

Toleo 4.3.1 lilikuwa toleo la sasa la 4.3 kufikia Agosti 2026 (4.4.0 imeshatolewa tangu wakati huo). Angalia ukurasa wa releases wa GitHub wa mradi huo, funga chochote kilicho cha sasa siku unayoi-deploy, kisha ubadilishe namba hiyo kwa makusudi. Image za hifadhi kwenye faili lililotolewa tayari zimefungwa kwenye matoleo makuu, postgres:17, clickhouse-server:25.12 na redis:7, na zinastahili kutendewa vivyo hivyo.

Iwashe.

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

Boot ya kwanza huendesha migrations, kwa hivyo ruhusu dakika moja au mbili kabla ya kitu chochote kujibu. docker compose ps inapaswa kuorodhesha huduma sita katika hali ya running. Ikiwa worker inajianzisha upya mara kwa mara, log yake ina sababu: CLICKHOUSE_MIGRATION_URL inatumia itifaki asilia ya ClickHouse kwenye port 9000, si port ya HTTP 8123, na kuielekeza kwenye 8123 kutafeli hapo wakati container ya wavuti bado inaonekana sawa.

Angalia afya ya mfumo kutoka kwenye seva yenyewe.

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

Wito rahisi wa /api/public/health unathibitisha tu kuwa mchakato wa API uko hai, kwa sababu unaruka database kwa makusudi ili huduma iendelee kufanya kazi wakati Postgres inapopata hitilafu ndogo. Fomu ya failIfDatabaseUnavailable=true ndiyo inayofaa kuelekezwa kwa monitor, na inarudisha 503 wakati database haipatikani. /api/public/ready inarudisha 200 mara tu migrations zinapokamilika na container itakapokubali trafiki. Zote mbili ni ukaguzi wa kawaida wa HTTP, kwa hivyo ukurasa wa hali wa Uptime Kuma unaweza kuzifuatilia na kukuambia kuwa stack imeshuka kabla ya mawakala wako kugundua.

Weka TLS mbele na ufunge port za ziada

Faili la compose lililosafirishwa huchapisha 3000:3000 kwa ajili ya container ya web na 9090:9000 kwa ajili ya MinIO. Zote hufungwa kwenye kila interface. Kwenye IP ya umma, hii inamaanisha yeyote anayechanganua port 3000 atafika kwenye ukurasa wako wa kujisajili, na yeyote anayechanganua 9090 atakuwa anazungumza na bucket inayohifadhi prompts zako ghafi.

Sheria ya firewall pekee haizifungi. Docker huandika sheria zake za DNAT kwenye jedwali la nat, na hizo hupitiwa kabla ya sheria za filter za ufw kuona pakiti, kwa hivyo ufw deny 3000 huacha port iliyochapishwa ikiwa wazi. Hili huathiri watu wengi kiasi cha kuwa na mwongozo wake: kwa nini port zilizochapishwa na Docker hupita ufw. Funga kwenye loopback katika faili lako la override badala yake.

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 lazima iwe anwani kamili ya umma ikijumuisha scheme, kwa sababu mchakato wa kuingia (login flow) hujenga URL yake ya callback kutoka kwa thamani hiyo. Ikiachwa kama http://localhost:3000 nyuma ya proxy ya HTTPS, mzunguko wa kuingia utatuma kivinjari mahali ambapo hakiwezi kufika.

Sasa elekeza reverse proxy kwenye 127.0.0.1:3000 na uiruhusu ishike cheti. Traefik katika mradi uleule wa Compose ndiyo chaguo la kawaida, na lebo za routing ni zile zilizofafanuliwa katika kuendesha programu kadhaa nyuma ya reverse proxy moja ya Traefik. Caddy hufanya kazi hiyo hiyo kwa mistari miwili ikiwa Langfuse ndiyo kitu pekee kwenye seva. Hakikisha kwa curl -sI https://langfuse.example.com/api/public/ready, kisha thibitisha kutoka kwa mashine ya pili kwamba curl http://YOUR_IP:3000 sasa inagoma (times out).

Tahadhari moja kuhusu MinIO. Langfuse hutumikia media iliyoambatishwa kwa kivinjari chako kupitia URL zilizotiwa saini (presigned URLs) zinazoelekeza kwenye endpoint hiyo ya S3, kwa hivyo ukitumia traces za aina nyingi (multi-modal) zenye picha au sauti, MinIO ya loopback pekee itamaanisha viambatisho hivyo havitapakia. Soma ukurasa wa usanidi wa blob storage kabla ya kuifanyia proxy, kwa sababu endpoint iliyoandikwa kwenye presigned URL lazima ilingane na unachochapisha. Traces za maandishi ya kawaida hazitaathirika.

Fungua akaunti yako wakati wa ziara ya kwanza, kisha ifanye instance hiyo iwe yako. Weka LANGFUSE_ALLOWED_ORGANIZATION_CREATORS kwenye anwani yako ya barua pepe, ili mgeni anayefika kwenye ukurasa huo asiweze kuunda shirika kwenye seva yako. Ikiwa tayari unaendesha Authentik kama mtoa huduma wako wa utambulisho, Langfuse inakubali muunganisho wa kawaida wa OIDC, kwa hivyo akaunti huja na kuondoka pamoja na programu zako nyingine badala ya kuishi kwenye orodha ya nywila ambayo ni seva hii pekee inayojua.

Tuma trace yako ya kwanza

Unda mradi katika kiolesura cha wavuti na unakili funguo zake za umma (public keys) na za siri (secret keys) kutoka kwenye mipangilio ya mradi. Python SDK husoma vigezo vitatu vya mazingira (environment variables).

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

LANGFUSE_BASE_URL ndilo jina la kigezo katika SDK v4, ambayo ilitolewa mnamo Machi 2026. Nambari za programu (code) za zamani na miongozo ya zamani hutumia LANGFUSE_HOST. Ikiwa trace zako zinafika kwenye Langfuse Cloud badala ya seva yako, sababu ni kwamba base URL haijawekwa, kwa sababu chaguo-msingi huelekeza kwenye mfumo uliopangishwa (hosted instance).

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 ya @observe hufungua uchunguzi (observation) kuzunguka kitendaji (function), hunasa hoja zake (arguments) na thamani inayorejeshwa, na kuiweka ndani ya uchunguzi wowote ambao tayari unafanya kazi. AnthropicInstrumentor ni zana ya OpenTelemetry ya Anthropic client, na hubadilisha kila mwito wa messages.create kuwa generation inayobeba jina la modeli, matumizi ya token, na latency, bila mabadiliko yoyote kwenye sehemu ya mwito huo.

Miito miwili hufanya ukaguzi kwa ajili yako. langfuse.auth_check() hurejesha False ikiwa funguo ni mbaya au base URL si sahihi, jambo ambalo ni la haraka zaidi kuliko kujiuliza kwa nini dashibodi haina data. langfuse.flush() husubiri hadi spans zilizopangwa kwenye foleni zitumwe, na michakato ya muda mfupi (short lived processes) inaihitaji, kwa sababu SDK hupanga data kwa makundi (batches) nyuma ya pazia na hati (script) inayojifunga mara moja hupoteza kundi lake ambalo halijatumwa.

Kwa nini ClickHouse inaendelea kukua?

Traces ndiyo data inayokua kwa kasi zaidi ambayo watu wengi hujihostia wenyewe. Kila uendeshaji wa agent huandika mstari mmoja kwa kila hatua, na inputs pamoja na outputs huhifadhiwa kikamilifu, kwa hivyo agent anayezungumza sana na prompts ndefu huzalisha bytes nyingi zaidi kwa siku kuliko programu anayoifuatilia. Ikiachwa bila kudhibitiwa, ClickHouse hujaza diski, na diski iliyojaa husimamisha ingestion badala ya kuipunguza kasi.

Mambo mawili tofauti hukua hapa, na yanahitaji masuluhisho mawili tofauti.

La kwanza ni data yako ya trace, na suluhisho ni mpangilio wa retention. Fungua mipangilio ya mradi katika web interface na uweke muda wa kuhifadhi data kwa siku. Langfuse inakubali kiwango cha chini cha siku 3. Kazi ya usiku huchagua traces, observations, scores na media assets zilizo na umri mkubwa kuliko muda huo na kuzifuta kutoka ClickHouse na kutoka blob storage. Kazi hiyo inahitaji ruhusa ya DeleteObject kwenye bucket, ambayo MinIO root credentials katika faili ya default compose tayari wanayo. Ufutaji ni wa kudumu, kwa hivyo sanidi export ya blob storage kwanza ikiwa unahitaji historia ya muda mrefu. Usiandike mwenyewe TTL clauses kwenye meza za Langfuse: kazi ya retention ndiyo inayoweka ClickHouse na bucket katika uwiano, na TTL ya mwongozo hufuta upande mmoja pekee.

Chagua muda kulingana na kile unachotumia kweli. Mapitio ya gharama na ubora hufanyika kwenye data ya siku chache zilizopita, si data ya miezi iliyopita. Siku 30 ni mwanzo mzuri kwa timu ndogo, na siku 14 zinatosha ikiwa unafungua trace tu wakati kitu kinapoharibika.

La pili ni meza za system log za ClickHouse yenyewe, na hili huwashangaza watu, kwa sababu diski huendelea kukua baada ya retention kusanidiwa. ClickHouse huandika trace_log, text_log, opentelemetry_span_log, metric_log na asynchronous_metric_log kwa ajili ya uchunguzi wake yenyewe, haziji na TTL, na Langfuse haizisomi kamwe. Tafuta kwanza mahali ambapo diski imejazwa.

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
)

Iendeshe kwa kutumia docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Ikiwa meza za mfumo ziko juu, zizime kwa kutumia config overlay, kwa sababu ClickHouse huunganisha kila faili katika /etc/clickhouse-server/config.d/ juu ya config yake kuu wakati wa kuanza.

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

Iweke (mount) na uanzishe upya ClickHouse.

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

Hiyo husimamisha uandishi mpya. Mistari iliyo tayari kwenye diski inabaki hapo, kwa hivyo rudisha nafasi hiyo kwa kutumia DROP TABLE IF EXISTS system.trace_log na vivyo hivyo kwa kila meza uliyoondoa. Ikiwa ungependa kuhifadhi diagnostics, mbadala wake ni TTL kali kwenye kila meza badala ya remove="1", ambayo nyaraka za scaling za Langfuse zinaelezea.

Meza nyingine moja inafaa kujulikana. blob_storage_file_log hufuatilia faili za tukio zilizopakiwa kwenye bucket yako. Ikiwa pia utaweka sera ya lifecycle kwenye bucket, ipe meza hiyo TTL inayolingana ili zisiachane.

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

Weka tahadhari ya kawaida ya df -h kwenye diski ya data pia. Traces hazikui kwa utaratibu. Hukua siku unapoachia agent mpya, na ishara ya kwanza ya hilo haipaswi kuwa ingestion kushindwa kufanya kazi.

Kuhifadhi nakala za Postgres na ClickHouse

Nakala ya Langfuse ina sehemu tatu. Postgres huhifadhi watumiaji, mashirika, miradi na API keys zako. ClickHouse huhifadhi traces. MinIO huhifadhi matukio (raw events). Ukirejesha Postgres pekee utapata mfumo wa kuingia (login) ambao hauna historia. Ukirejesha ClickHouse pekee utapata historia ambayo hakuna mtu anayeweza kuingia ili kuiona.

Postgres ni pg_dump ya kawaida, ambayo ndiyo inayopendekezwa na nyaraka za nakala za Langfuse.

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

ClickHouse inahitaji uangalifu zaidi, kwa sababu saraka ya data inayofanya kazi ikinakiliwa wakati merges zinaendelea haitakuwa nakala thabiti. Njia rahisi kwenye seva moja ni kusimamisha container na kuhifadhi volume kwenye archive.

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

Tumia jina la volume ambalo docker volume ls inatoa, si lile lililoandikwa kwenye YAML. Faili hutangaza langfuse_clickhouse_data, na Compose huongeza jina la mradi mwanzo, kwa hivyo clone katika saraka inayoitwa langfuse itazalisha langfuse_langfuse_clickhouse_data. Ukikosea hapo, docker run itatengeneza volume mpya tupu bila kutoa onyo, na archive yako haitakuwa na kitu.

Container ya web huandika kila tukio linaloingia kwenye bucket kabla ya worker kulichakata, kwa hivyo kusimamisha ClickHouse kwa muda mfupi kunamaanisha kuwa worker itajaribu tena baadaye. Fanya hivi wakati wa saa za utulivu na ufanye kwa muda mfupi. Kwa instance yenye shughuli nyingi, taarifa ya BACKUP DATABASE default TO S3(...) ya ClickHouse yenyewe huandika nakala thabiti bila kusimamisha seva. MinIO ni sehemu ya tatu, na mc mirror au MinIO replication kwenye bucket ya nje inatosha. Chochote unachozalisha, kitoe kwenye seva hiyo, ndiyo maana ya encrypted restic backups on a VPS.

Redis haihitaji nakala. Inashikilia queue na cache, kwa hivyo kuipoteza kunakugharimu tu matukio yanayochakatwa wakati huo na si kitu cha zamani.

Tahadhari kuhusu uthabiti (consistency) ni ya kweli na inafaa kusemwa wazi. Postgres na ClickHouse hutolewa nakala (dump) kwa nyakati tofauti, kwa hivyo urejeshaji unaweza kuacha safu ya mradi bila traces, au traces zinazomilikiwa na mradi ambao haupo tena. Langfuse huvumilia hali hiyo, lakini chukua nakala zote mbili kwa wakati mmoja na wakati wa trafiki ndogo. Bucket ya matukio ndiyo wavu halisi wa usalama, kwa sababu Langfuse huhifadhi kila tukio linaloingia huko kabla ya kulichakata.

Rejesha kwenye stack ya majaribio angalau mara moja. Hivyo ndivyo unavyoweza kugundua jina la volume lisilo sahihi sasa, badala ya kugundua wakati wa hitilafu.

Mambo ya kwanza kuangalia

Mambo manne yanastahili kupewa kipaumbele katika wiki ya kwanza.

• Gharama kwa kila trace. Langfuse huhesabu gharama kulingana na jina la model na matumizi ya token, kwa hivyo panga traces kulingana na gharama na usome ile ya gharama kubwa zaidi kuanzia mwanzo hadi mwisho. Jibu mara nyingi ni prompt iliyokua: hati nzima iliyobandikwa kwenye context, au historia ya mazungumzo ambayo hakuna anayeipunguza. Mara tu unapoiona, kudhibiti gharama za AI agent inakuwa kazi ya kihandisi badala ya kubahatisha.
• Mgawanyo wa matumizi ya token kwa input na output. Input tokens ni nyingi na za bei nafuu, output tokens ni chache na za gharama, na input iliyohifadhiwa (cached) ni ya bei nafuu zaidi. Uhasibu uleule unafafanuliwa katika jinsi matumizi ya token ya Claude Code yanavyohesabiwa, na unatumika kwa wakala yeyote unayejijengea mwenyewe.
• Asilimia za latency (Latency percentiles). Wastani (median) huficha tatizo. p95 na p99 ndipo timeouts zinapojificha, na ndani ya loop ya wakala, tool call ya polepole katika p95 huzidishwa kwa idadi ya marudio (iterations).
• Tool calls zilizofeli. Chuja observations kwa kutumia level ERROR. Chombo kinachofeli kwa asilimia 5 ya muda hakionekani katika kiwango cha jumla cha mafanikio, lakini kinaonekana wazi katika traces, ambapo unatazama model ikijaribu tena na kuteketeza tokens ikijaribu kukwepa tatizo hilo.

Weka muda wa kuhifadhi data (retention window) na uchague dashboard utakayoiangalia kila wiki siku ileile unayofanya deployment. Chombo cha ufuatiliaji (observability tool) ambacho hakuna anayekifungua ni database inayojaza diski tu.

FAQ

Langfuse inayojiendesha yenyewe inahitaji kumbukumbu kiasi gani?

Panga kuwa na CPU cores 4 na 16 GiB ya kumbukumbu, ambayo ndiyo inayopendekezwa na mwongozo wa Langfuse Docker Compose kwa mashine moja ya mtandaoni (virtual machine), pamoja na takriban 100 GiB ya hifadhi. Viwango vya chini vilivyochapishwa kwa vipengele ni 8 GiB kwa ClickHouse na 4 GiB kila moja kwa container za web na worker, huku Postgres, Redis na MinIO zikihitaji kumbukumbu zaidi ya hizo. 8 GiB inatosha kuendesha instance ya msanidi mmoja. 2 GiB haitoshi: ClickHouse huuwawa na kernel wakati wa background merges, na dmesg inaonyesha Out of memory: Killed process.

Kwa nini diski ya ClickHouse huendelea kujaa baada ya kuweka data retention?

Mpangilio wa retention unahusu data ya Langfuse pekee. ClickHouse huandika meza zake za uchunguzi trace_log, text_log, opentelemetry_span_log, metric_log na asynchronous_metric_log kando, na hizi hazina TTL. Tumia query system.parts iliyopangwa kwa meza ili kuona ni ipi kubwa zaidi, kisha zima meza zisizotumika kwa kuingiza remove="1" kwenye faili iliyo chini ya /etc/clickhouse-server/config.d/, anzisha upya ClickHouse, na ufute meza zilizopo ili kurejesha nafasi iliyotumika.

Muda wa chini kabisa wa kuhifadhi data (data retention) katika Langfuse ni upi?

Siku tatu. Retention huwekwa kwa kila mradi katika mipangilio ya mradi, au kupitia API ya miradi, na kazi ya usiku hufuta traces, observations, scores na media assets zilizo na umri mkubwa kuliko muda huo kutoka ClickHouse na blob storage. Ufutaji hauwezi kutenduliwa, kwa hivyo sanidi export ya blob storage kwanza ikiwa unahitaji historia zaidi ya muda huo.

Je, lazima nifanye backup ya Postgres na ClickHouse zote mbili?

Ndiyo, kwa sababu zinahifadhi vitu tofauti. Postgres huhifadhi watumiaji, mashirika, miradi na API keys, na ClickHouse huhifadhi data ya trace yenyewe. Restore ya Postgres pekee itakupa instance unayoweza kuingia lakini haina kitu ndani. Fanya backup ya MinIO bucket pia, kwa sababu inahifadhi raw events ambazo Langfuse hupokea, ambayo ndiyo kitu cha karibu zaidi na chanzo cha ukweli (source of truth) katika stack hii.

Je, ninaweza kuelekeza usanidi wa OpenTelemetry uliopo kwenye Langfuse inayojiendesha yenyewe?

Ndiyo. Langfuse v4 na SDK zake za v4 zimejengwa juu ya OpenTelemetry, na instrumentations za Anthropic na OpenAI OTel hu-export moja kwa moja kwake. Katika Python, endesha pip install langfuse opentelemetry-instrumentation-anthropic, ita AnthropicInstrumentor().instrument() mara moja wakati wa kuanza, na uweke LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY na LANGFUSE_BASE_URL kwenye host yako mwenyewe. Thibitisha na langfuse.auth_check() kabla ya kuanza kutafuta dashboard inayokosekana.