Jinsi ya kujiendeshea Langfuse kwenye VPS yako
Jifunze kusanidi Langfuse ili kufuatilia wakala wako wa AI. Mwongozo huu unaelezea matumizi ya ClickHouse, usanidi wa TLS, uhifadhi wa data na mbinu sahihi za kuhifadhi nakala.
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 Langfuse ya kujihostia huendesha
Langfuse v4 si kontena moja. Ni kontena mbili za programu na huduma nne za hifadhi, na kwenye VPS moja, zote sita huendeshwa kwenye seva yako.
langfuse-webhuhudumia kiolesura cha wavuti na API ya kumeza data (ingestion API).langfuse-workerhuondoa data kwenye foleni (queue) kwa nyuma. Huchakata makundi ya data, huhesabu gharama, na huendesha kazi ya kila usiku ya kuhifadhi data (retention job).- Postgres huhifadhi data za miamala kama vile watumiaji, mashirika, miradi, funguo za API, na prompts.
- ClickHouse huhifadhi data za trace zenyewe, yaani observations na scores. Hii ni hifadhi ya safu (column store) iliyoundwa kwa ajili ya hoja za uchanganuzi, ndiyo maana dashibodi yenye safu (rows) milioni mia moja bado hujibu haraka.
- Redis ni foleni na akiba (cache) iliyopo kati ya wavuti na mfanyakazi (worker).
- MinIO hukupa hifadhi ya vitu (object storage) inayooana na S3 kwenye seva yako. Huhifadhi kila tukio ghafi linaloingia pamoja na midia yoyote unayoiambatanisha.
Langfuse huchapisha rasilimali za chini kabisa kwa kila kijenzi inachokiendesha. Chati inaonyesha vile vitatu vinavyofanya kazi.
Data iliyo nyuma ya chati hii
[
{
"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 huomba 8 GiB ya kumbukumbu. Kontena la wavuti na mfanyakazi huomba 4 GiB kila moja. Hizo ndizo sakafu zilizochapishwa kwa ajili ya vijenzi 3 vilivyo kwenye chati. Ukurasa huo huo huorodhesha Postgres kwa 4 GiB, Redis au Valkey kwa 1.5 GiB, na MinIO kwa 4 GiB, kwa hivyo kiwango cha chini kwa vyote sita ni 25.5 GiB. Mwongozo wa Docker Compose wa mradi wenyewe unapendekeza angalau cores 4, 16 GiB ya kumbukumbu, na takriban 100 GiB ya hifadhi kwa mashine moja. Hiyo ni chini ya jumla ya sakafu za vijenzi, kwa hivyo chukulia 16 GiB kama kiwango cha chini kabisa ambacho Compose box iliyoshirikiwa inahitaji, si kama nafasi ya ziada.
Usijaribu hili kwenye mpango wa 2 GiB. ClickHouse huanza, hukubali uandishi kwa muda, kisha hufa wakati wa kuunganisha data kwa nyuma (background merge), kwa sababu muunganisho hupakia sehemu kubwa za jedwali kwenye kumbukumbu. Utaona docker compose ps ikiripoti kontena la clickhouse kama restarting, dmesg ikiwa na mstari kama Out of memory: Killed process 1234 (clickhouse-serv), na kila dashibodi ya Langfuse ikirudisha 500. Chini ya shinikizo dogo, ClickHouse hukataa hoja hiyo na kuingiza DB::Exception: Memory limit (total) exceeded kwenye logi. Kumi na sita ndiyo namba ya kupanga. Ikiwa VPS hiyo hiyo inakusudiwa kubeba kitu kingine chochote, tengeneza bajeti kwa ajili ya hicho kando, kwa sababu hata stack nyepesi kiasi kama workspace ya AFFiNE inayojihostiwa inataka gigabytes zake na ClickHouse haitarudisha chochote.
Kuweka Langfuse kwa kutumia Docker Compose
Clone hazina (repository) hiyo. Stack, muunganisho, na mazingira chaguo-msingi vyote vinapatikana ndani ya docker-compose.yml yake.
git clone https://github.com/langfuse/langfuse.git
cd langfuseKila thamani unayopaswa kubadilisha imewekwa alama ya # CHANGEME kwenye faili hilo. Tengeneza siri tatu za programu (application secrets) kwanza.
openssl rand -base64 32 # NEXTAUTH_SECRET
openssl rand -base64 32 # SALT
openssl rand -hex 32 # ENCRYPTION_KEYENCRYPTION_KEY lazima iwe na bits 256 zilizoandikwa kama vibambo 64 vya hex, ambavyo ndivyo hasa openssl rand -hex 32 inavyochapisha. Inaficha thamani nyeti zilizohifadhiwa, ikiwemo funguo zozote za mtoa huduma wa LLM unazohifadhi kwenye instance hiyo. Ibadilishe baada ya data kuwepo na safu hizo hazitaweza kufichuliwa tena, kwa hivyo ichukulie kama ya kudumu tangu boot ya kwanza. SALT inatumika kuhash funguo zako za Langfuse API, kwa hivyo kuibadilisha kutabatilisha kila ufunguo ambao mawakala wako wanautumia tayari.
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 inaingia kwenye log ya worker wakati interface ya wavuti bado inaonekana kuwa sawa. Kuhifadhi thamani hizi kwenye faili la env badala ya faili la compose linalofuatiliwa ndiyo mbinu inayoelezewa katika Docker Compose env files and secrets.
Funga (pin) tag za image kabla ya kuanza
Faili lililosafirishwa linatumia docker.langfuse.com/langfuse/langfuse:4 na docker.langfuse.com/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 ni migration ya schema isiyopangwa kwenye database ambayo hukuihifadhi (backup) asubuhi hiyo. Funga zote mbili kwenye release moja katika docker-compose.override.yml, ambayo Compose huiunganisha juu ya faili lililosafirishwa ili git pull ya baadaye isigongane na marekebisho yako. Image zilezile huchapishwa kwenye Docker Hub, ambapo override hapa chini huzivuta kutoka.
services:
langfuse-web:
image: docker.io/langfuse/langfuse:4.72.0
langfuse-worker:
image: docker.io/langfuse/langfuse-worker:4.72.0Toleo la 4.3.1 lilikuwa toleo la sasa la 4.3 kufikia Agosti 2026. Matoleo yamekuwa yakitoka haraka tangu wakati huo, na v4.56.0 lilikuwa la hivi karibuni kwenye GitHub kufikia Oktoba 11, 2026. Override hapo juu inatumia v4.72.0, toleo la hivi karibuni kwenye GitHub kufikia Oktoba 31, 2026. Angalia ukurasa wa releases wa GitHub wa mradi huo, funga toleo lolote lililo la sasa siku unayoweka, kisha ubadilishe namba hiyo kwa makusudi. Baadhi ya image za hifadhi kwenye faili lililosafirishwa zinastahili matibabu hayo hayo, kwa sababu tag zake pia hubadilika. postgres:17 (chaguo-msingi la variable ya POSTGRES_VERSION) na redis:7 hufuata toleo kuu. Faili lililosafirishwa sasa linatumia tag ya toleo kamili kwa docker.io/clickhouse/clickhouse-server, likifunga toleo kamili la ClickHouse. Kanuni hiyo si mahususi kwa Langfuse: a self-hosted openGym workout tracker huendesha sehemu ndogo ya stack hii na bado inahitaji git tag iliyotajwa, kwa sababu chochote kinachofanya migration ya database yake yenyewe wakati wa kuanza kinaweza kugeuza pull ya kawaida kuwa mabadiliko ya schema.
Ianzishe.
docker compose up -d
docker compose ps
docker compose logs -f langfuse-workerBoot ya kwanza huendesha migrations, kwa hivyo ruhusu dakika mbili au tatu kabla ya kitu chochote kujibu. Container ya wavuti huingiza Ready mara tu inapokuwa tayari. docker compose ps inapaswa kuorodhesha huduma sita katika hali ya running. Ikiwa container inaanza upya katika mzunguko, log yake ina sababu. Migrations za ClickHouse hutumika wakati container ya wavuti inapoanza, kwa hivyo CLICKHOUSE_MIGRATION_URL mbaya huonekana katika docker compose logs langfuse-web, si katika log ya worker unayofuatilia. Variable hiyo inatumia itifaki ya asili ya ClickHouse kwenye port 9000, si port ya HTTP 8123, na kuielekeza kwenye 8123 kunaharibu migrations za kuanza kwa container ya wavuti. Worker huendesha migrations za nyuma (background) ambazo ni polepole, kwa hivyo log yake ndiyo mahali ambapo hizo huripoti.
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/readyAmri rahisi ya /api/public/health inathibitisha tu kuwa mchakato wa API uko hai, kwa sababu kwa chaguo-msingi haikagui database. Fomu ya failIfDatabaseUnavailable=true ndiyo inayostahili kuelekezwa kwa monitor, na inarudisha 503 wakati database haipatikani. /api/public/ready inarudisha 200 wakati container ya wavuti iko tayari kupokea trafiki, na 500 mara tu inapoambiwa kuzima. Zote mbili ni ukaguzi wa kawaida wa HTTP, kwa hivyo an Uptime Kuma status page inaweza 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 mbili hufungwa kwenye kila interface. Kwenye IP ya umma, hii inamaanisha yeyote anayechanganua port 3000 anafikia ukurasa wako wa kujisajili, na yeyote anayechanganua 9090 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 kichujio 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. Tumia !override na Docker Compose 2.24.4 au toleo jipya zaidi ili kuchukua nafasi ya port zilizochapishwa; orodha ya kawaida huunganishwa na bindings za awali.
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 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. Kwa Traefik katika mradi uleule wa Compose, elekeza kwenye langfuse-web:3000 kupitia mtandao wa Compose kwa kutumia lebo zilizoelezwa 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. Thibitisha kwa curl -sI https://langfuse.example.com/api/public/ready, kisha hakikisha kutoka kwa mashine ya pili kuwa curl http://YOUR_IP:3000 haiwezi kuunganishwa.
Tahadhari moja kuhusu MinIO. Langfuse hutoa URL zilizosainiwa mapema (presigned URLs) zinazoelekeza kwenye endpoint hiyo ya S3, kwa SDK zinazopakia media na kwa kivinjari chako kinachozipakia. Kwa hivyo, ukitumia traces za aina nyingi (multi-modal) zenye picha au sauti, MinIO ya loopback pekee inamaanisha viambatisho hivyo havitapakia kutoka kwa mashine nyingine au kupakia kwenye kivinjari chako. Soma ukurasa wa usanidi wa blob storage kabla ya kuifanyia proxy, kwa sababu endpoint iliyoandikwa kwenye presigned URL, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, lazima ilingane na kile unachochapisha. Traces za maandishi ya kawaida hazijaathiriwa.
Fungua akaunti yako wakati wa ziara ya kwanza, kisha ifanye instance hiyo iwe yako. Weka AUTH_DISABLE_SIGNUP=true mara tu akaunti yako inapokuwepo, ili mgeni anayefika kwenye ukurasa ashindwe kujisajili kabisa. Langfuse pia ina LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, ambayo huzuia nani anaweza kuunda mashirika, lakini ni kipengele cha Enterprise Edition na hufanya kazi tu na ufunguo wa leseni. 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 seva hii pekee ndiyo inayojua.
Tuma trace yako ya kwanza
Unda mradi katika kiolesura cha wavuti na unakili funguo zake za umma na za siri kutoka kwa 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 ni jina la kigezo katika SDK v4, ambayo ilitolewa Machi 2026. Nambari za zamani na miongozo ya zamani hutumia LANGFUSE_HOST. Ikiwa trace zako zinatua kwenye Langfuse Cloud badala ya seva yako, URL ya msingi (base URL) ambayo haijawekwa ndiyo sababu, kwa sababu chaguo-msingi huelekeza kwenye mfano uliopangishwa (hosted instance).
Python SDK v5 ya sasa inahitaji Python 3.11 au baadaye na Langfuse v4.59.0 ya kujihostia au baadaye, ambayo seva iliyobandikwa hapo juu inakidhi.
pip install langfuse opentelemetry-instrumentation-anthropic anthropicimport 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()Kipambo (decorator) cha @observe hufungua observation kuzunguka kitendakazi, hunasa hoja zake na thamani yake ya kurudi, na kukiweka chini ya observation yoyote ambayo tayari inafanya kazi. AnthropicInstrumentor ni instrumentation ya OpenTelemetry kwa ajili ya mteja wa Anthropic, na hubadilisha kila wito wa messages.create kuwa kizazi (generation) kinachobeba jina la modeli, matumizi ya token, na latency, bila mabadiliko yoyote kwenye tovuti ya wito.
Wito mbili hufanya ukaguzi kwa ajili yako. langfuse.auth_check() hurudisha False kwenye funguo mbaya au URL ya msingi isiyo sahihi, ambayo ni haraka kuliko kujiuliza kwa nini dashibodi haina kitu. langfuse.flush() huzuia hadi spans zilizopangwa kwenye foleni zitumwe, na michakato ya muda mfupi inaihitaji, kwa sababu SDK hufanya kazi kwa makundi kwa nyuma na hati inayotoka mara moja huchukua kundi lake lisilotumwa pamoja nayo. Ikiwa timu nzima inatuma trace badala ya hati moja, weka vigezo hivyo vitatu mara moja kwenye gateway ambayo mawakala wa kila mtu tayari wanapitia badala ya kwenye shell ya kila mtu, ambayo ndiyo njia ambayo harness ya OneCLI inayojihostiwa huweka mbio za kila mfanyakazi zikiwa zimepimwa (instrumented) wakati funguo zikiwa mahali pamoja.
Kwa nini ClickHouse inaendelea kukua?
Traces ndiyo data inayokua kwa kasi zaidi ambayo watu wengi hujiendeshea wenyewe (self-host). Kila wakala (agent) anapoendesha kazi, huandika safu moja kwa kila hatua, na pembejeo pamoja na matokeo huhifadhiwa kikamilifu. Hivyo, wakala anayezungumza sana na mwenye prompts ndefu huzalisha baiti nyingi zaidi kwa siku kuliko programu anayoifuatilia. Ikiachwa bila kudhibitiwa, ClickHouse hujaza diski, na diski iliyojaa husimamisha uingizaji wa data (ingestion) badala ya kuupunguza kasi.
Kuna mambo mawili tofauti yanayokua hapa, na yanahitaji masuluhisho mawili tofauti.
La kwanza ni data yako ya trace, na suluhisho lake ni mpangilio wa retention. Kwenye instance inayojiendesha yenyewe, retention ya data ni kipengele cha Enterprise Edition na inahitaji license key. Bila hiyo, Langfuse huhifadhi traces, observations, scores, na media bila kikomo. Kwa hivyo, kadiria ukubwa wa diski kwa ajili hiyo na utegemee tahadhari ya diski mwishoni mwa sehemu hii. Ukiwa na license, wamiliki wa mradi na wasimamizi wanaweza kufungua mipangilio ya mradi na kuweka muda wa kuhifadhi data kwa siku. Langfuse inakubali kuanzia siku 3. Kazi ya kila usiku huchagua traces, observations, scores, na media assets zilizo na umri mkubwa kuliko muda huo na kuzifuta kutoka ClickHouse na kutoka kwenye blob storage, isipokuwa media inayohusishwa na vitu vilivyohifadhiwa kwenye dataset. Kazi hiyo inahitaji ruhusa ya DeleteObject kwenye bucket, ambayo vitambulisho vya root vya MinIO katika faili ya kawaida ya compose tayari vinayo. Ufutaji ni wa kudumu, kwa hivyo sanidi usafirishaji wa blob storage kwanza ikiwa unahitaji historia ya muda mrefu. Usiandike mwenyewe vifungu vya TTL kwenye majedwali ya Langfuse: kazi ya retention ndiyo inayoweka ClickHouse na bucket katika usawaziko, na TTL ya mwongozo hufuta upande mmoja pekee.
Chagua muda kulingana na kile unachotumia kikweli. 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 pale tu kitu kinapoharibika.
La pili ni majedwali ya logi ya mfumo wa ClickHouse yenyewe, na hili huwashangaza watu, kwa sababu diski huendelea kukua hata baada ya retention kusanidiwa. ClickHouse huandika trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log na latency_log kwa ajili ya uchunguzi wake wa ndani, hayaji na TTL yoyote, na Langfuse haiyasomi kamwe. Kwanza, gundua ni wapi 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 majedwali ya mfumo yapo juu kwenye orodha, yazime kwa kutumia config overlay, kwa sababu ClickHouse huunganisha kila faili iliyo kwenye /etc/clickhouse-server/config.d/ juu ya usanidi wake mkuu 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"/>
<latency_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:roHiyo husimamisha uandikaji mpya. Safu zilizopo tayari kwenye diski zitabaki, kwa hivyo rudisha nafasi hiyo kwa kutumia DROP TABLE IF EXISTS system.trace_log na ufanye vivyo hivyo kwa kila jedwali uliloliondoa. Ikiwa ungependa kuhifadhi uchunguzi huo, njia mbadala ni kuweka TTL kali kwenye kila jedwali badala ya remove="1", jambo ambalo nyaraka za scaling za Langfuse zinaelezea. Maelekezo hayo ya TTL hutumika tu wakati jedwali la mfumo linapoundwa kwa mara ya kwanza, kwa hivyo kwenye usakinishaji uliopo, nyaraka hizo hizo zitakuongoza jinsi ya kurekebisha majedwali hayo.
Kuna jedwali moja zaidi unalopaswa kulijua. blob_storage_file_log hufuatilia faili za matukio zilizopakiwa kwenye bucket yako. Ikiwa pia umeweka sera ya lifecycle kwenye bucket, ipe jedwali hilo TTL inayolingana ili yote mawili yasipishane.
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 unapoanzisha wakala mpya, na ishara ya kwanza ya hilo haipaswi kuwa kushindwa kwa ingestion.
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 raw events. Ukirejesha Postgres pekee utapata mfumo wa kuingia (login) unaofanya kazi lakini bila historia. Ukirejesha ClickHouse pekee utapata historia ambayo hakuna mtu anayeweza kuingia ili kuiona. Mgawanyo huu si wa kipekee kwa Langfuse, na kituo cha usaidizi cha Chatwoot kinachojiendesha kina muundo uleule, ambapo dump ya Postgres iliyochukuliwa bila saraka ya uploads hurejesha mazungumzo ambayo viambatisho vyake vyote vimepotea.
Postgres ni pg_dump ya kawaida, ambayo ndiyo inayotumiwa na nyaraka za nakala za Langfuse kwa usakinishaji wa Docker.
docker compose exec -T postgres pg_dump -U postgres postgres \
| gzip > langfuse-pg-$(date +%F).sql.gzClickHouse inahitaji uangalifu zaidi, kwa sababu saraka ya data inayotumika ikinakiliwa wakati merges zinaendelea haitakuwa nakala thabiti. Njia rahisi kwenye seva moja ni kusimamisha container na kuhifadhi volume hiyo 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 clickhouseTumia jina la volume ambalo docker volume ls inatoa, si lile lililoandikwa kwenye YAML. Faili hutangaza langfuse_clickhouse_data, na Compose huongeza jina la mradi mwanzoni, kwa hivyo clone katika saraka inayoitwa langfuse huzalisha langfuse_langfuse_clickhouse_data. Ukikosea hapo, docker run itatengeneza volume mpya tupu bila kutoa onyo, na archive yako haitakuwa na kitu.
Langfuse hupakia raw event data kwenye bucket katika kila ombi la ingestion na kuisoma tena ili kujaribu tena kazi za ingestion zilizofeli, kwa hivyo kusimamisha ClickHouse kwa muda mfupi mara nyingi humaanisha kuwa worker itajaribu tena baadaye. Fanya hivi wakati wa utulivu na uweke muda mfupi. Kwa instance yenye shughuli nyingi, taarifa ya BACKUP DATABASE default TO S3(...) ya ClickHouse yenyewe huandika nakala thabiti bila kusimamisha seva. MinIO ndiyo sehemu ya tatu, na mc mirror au MinIO replication kwenye bucket iliyo nje ya seva huishughulikia. Chochote unachozalisha, kitoe kwenye seva hiyo, ndiyo maana ya nakala za restic zilizosimbwa kwenye VPS.
Redis huhifadhi queue na cache. Kuipoteza kutafuta kazi zilizokuwa kwenye queue, hata kama faili zao za raw event bado zipo kwenye bucket.
Tahadhari kuhusu uthabiti ni ya kweli na inafaa kusemwa wazi. Postgres na ClickHouse huchukuliwa dumps kwa nyakati tofauti, kwa hivyo urejeshaji unaweza kuacha safu ya mradi bila traces, au traces zinazomilikiwa na mradi ambao haupo tena. Langfuse huvumilia hilo, lakini chukua dumps zote mbili kwa wakati mmoja na katika kipindi cha trafiki ndogo. Event bucket ndiyo wavu halisi wa usalama, kwa sababu Langfuse hupakia raw event data huko katika kila ombi la ingestion.
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. Kiwango cha chini cha vipengele kilichochapishwa ni 8 GiB kwa ClickHouse na 4 GiB kila moja kwa kontena za web na worker. Ukurasa huo huo unaorodhesha 4 GiB kwa Postgres, 1.5 GiB kwa Redis na 4 GiB kwa MinIO, hivyo vyote sita kwa pamoja vinafikia 25.5 GiB, kiasi ambacho ni kikubwa kuliko 16 GiB inayopendekezwa na Compose.
Kwa nini diski ya ClickHouse inaendelea kujaa baada ya kuweka data retention?
Mpangilio wa retention unahusu data ya Langfuse pekee. ClickHouse huandika meza zake za uchunguzi (diagnostic tables) trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log na latency_log kando, na hizi hazina TTL yoyote. 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 Organization Management API, na kazi ya usiku hufuta traces, observations, scores na media assets zilizo na umri mkubwa kuliko muda huo kutoka ClickHouse na blob storage, isipokuwa media inayohusishwa na vitu vilivyohifadhiwa kwenye dataset. Kwenye instance inayojiendesha yenyewe, hii ni kipengele cha Enterprise Edition kinachohitaji license key. Bila hiyo, data huhifadhiwa bila ukomo. Ufutaji hauwezi kutenduliwa, kwa hivyo sanidi usafirishaji wa 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 inahifadhi watumiaji, mashirika, miradi na API keys, na ClickHouse inahifadhi data ya trace yenyewe. Urejeshaji wa Postgres pekee utakupa instance unayoweza kuingia lakini haina kitu ndani yake. Fanya backup ya MinIO bucket pia, kwa sababu inahifadhi raw events ambazo Langfuse huzihifadhi mara tu zinapowasili, 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 sasa zimejengwa juu ya OpenTelemetry, na instrumentations za Anthropic na OpenAI OTel husafirisha data 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.