Paano i-self-host ang Langfuse para i-trace ang AI agent
Alamin ang resource floor sa VPS, tamang pinned image tags, TLS, ClickHouse retention bago mapuno ang disk, at backup na talagang nare-restore.
Bakit kailangang i-trace ang AI agent
Maaari mong i-self-host ang Langfuse upang makita kung ano talaga ang ginawa ng iyong agent sa isang run. Ang Langfuse ay isang open source na LLM (large language model) observability tool. Itinatala nito ang bawat prompt, bawat response ng model, bawat tool call, at bawat token, saka pinagsasama ang mga ito sa iisang trace na maaari mong buksan at basahin. Kapag pinatakbo mo ito sa sarili mong VPS, hindi lumalabas sa server na kontrolado mo ang mga prompt na iyon.
Simple ang dahilan kung bakit ito mahalaga. Hindi mo maaayos ang cost problem o quality problem na hindi mo nakikita. Sinasabi ng provider invoice na apat na beses na mas mataas ang gastos noong Tuesday kaysa noong Monday. Sinasabi ng trace kung aling agent run ang sanhi nito, kung aling prompt ang lumaki sa 40,000 tokens, at kung aling retry loop ang siyam na beses na tumakbo bago sumuko. Ibinibigay ng invoice ang numero. Ipinapakita ng trace ang code na gumawa nito.
Tatlong termino ang gagamitin sa buong guide na ito. Ang trace ay isang end-to-end na run ng iyong agent. Ang observation ay isang hakbang sa loob ng run na iyon: isang span para sa ordinaryong code at isang generation para sa tawag sa model. Ang score ay numerong naka-attach sa isang trace mula sa human review o automated evaluator. Gumagamit ang Langfuse ng OpenTelemetry (OTel), ang vendor-neutral na standard para sa distributed tracing, kaya maaari itong pagdalhan ng instrumentation na mayroon ka na.
Ano talaga ang pinapatakbo ng self-hosting ng Langfuse
Ang Langfuse v4 ay hindi isang container lamang. Binubuo ito ng dalawang application container at apat na storage service. Sa isang VPS, lahat ng anim ay tumatakbo sa server mo.
langfuse-webang nagsisilbi sa web interface at ingestion API.langfuse-workerang kumokonsumo sa queue sa background. Pinoproseso nito ang ingestion batch, kinakalkula ang cost, at pinapatakbo ang nightly retention job.- Ang Postgres ang nag-iimbak ng transactional data gaya ng mga user, organisasyon, project, API key, at prompt.
- Ang ClickHouse ang nag-iimbak ng mismong trace data, kabilang ang observations at scores. Isa itong column store na ginawa para sa analytical query. Kaya mabilis pa ring sumagot ang dashboard kahit lampas isang daang milyong row na ang laman.
- Ang Redis ang queue at cache sa pagitan ng web at worker.
- Nagbibigay ang MinIO ng S3-compatible object storage sa server. Iniimbak nito ang bawat raw incoming event at anumang media na ikinakabit mo.
Naglalathala ang Langfuse ng minimum resources para sa bawat component na pinapatakbo nito. Ipinapakita ng chart ang tatlong component na gumagawa ng aktuwal na processing.
Ang datos sa likod ng tsart na ito
[
{
"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
}
]Ang ClickHouse lamang ay nangangailangan na ng 8 GiB na memory. Ang web container at worker ay nangangailangan ng tig-4 GiB. Ito ang published floor para sa 3 component sa chart. Nakalista rin sa parehong page ang 4 GiB para sa Postgres, 1.5 GiB para sa Redis o Valkey, at 4 GiB para sa MinIO. Dahil dito, umaabot sa 25.5 GiB ang minimum para sa lahat ng anim. Inirerekomenda ng sariling Docker Compose guide ng project ang hindi bababa sa 4 core, 16 GiB na memory, at humigit-kumulang 100 GiB na storage para sa isang machine. Mas mababa ito kaysa sa pinagsamang floor ng mga component, kaya ituring ang 16 GiB bilang pinakamababang kailangan ng shared Compose server, hindi bilang headroom.
Huwag itong subukan sa 2 GiB plan. Nagsisimula ang ClickHouse at tumatanggap ng writes nang ilang sandali, pero namamatay ito habang may background merge dahil nilo-load ng merge ang malalaking bahagi ng table sa memory. Makikita mo ang docker compose ps na nag-uulat na ang clickhouse container ay restarting, ang dmesg na may linyang gaya ng Out of memory: Killed process 1234 (clickhouse-serv), at magbabalik ng 500 ang bawat Langfuse dashboard. Kapag mas magaan ang pressure, tatanggihan na lamang ng ClickHouse ang query at magla-log ng DB::Exception: Memory limit (total) exceeded. Labing-anim ang dapat mong gawing batayan sa pagpa-plano. Kung may iba pang kailangang patakbuhin sa parehong VPS, maglaan ng hiwalay na resources para rito dahil kahit ang mas magaan na stack gaya ng self-hosted na AFFiNE workspace ay nangangailangan ng sarili nitong gigabytes, at walang ibabalik na memory ang ClickHouse.
I-deploy ang Langfuse gamit ang Docker Compose
I-clone ang repository. Ang stack, wiring, at default environment ay nasa docker-compose.yml nito.
git clone https://github.com/langfuse/langfuse.git
cd langfuseAng bawat value na kailangan mong baguhin ay may markang # CHANGEME sa file na iyon. I-generate muna ang tatlong application secret.
openssl rand -base64 32 # NEXTAUTH_SECRET
openssl rand -base64 32 # SALT
openssl rand -hex 32 # ENCRYPTION_KEYAng ENCRYPTION_KEY ay dapat 256 bits na nakasulat bilang 64 hexadecimal character. Eksaktong ganito ang inilalabas ng openssl rand -hex 32. Ine-encrypt nito ang mga sensitibong value habang naka-store, kasama ang anumang LLM provider key na ise-save mo sa instance. Kapag pinalitan mo ito matapos magkaroon ng data, hindi na made-decrypt ang mga row na iyon. Ituring itong permanenteng value mula sa unang boot. Ginagamit ang SALT para i-hash ang iyong Langfuse API key. Kapag binago mo ito, mai-invalidate ang lahat ng key na ginagamit na ng iyong mga agent.
Pagkatapos, itakda ang POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH at MINIO_ROOT_PASSWORD. Lumilitaw ang MinIO password sa apat na lugar: una bilang MINIO_ROOT_PASSWORD, pagkatapos bilang LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY at LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Kapag may nakaligtaan ka, tatanggihan ng MinIO ang client na iyon gamit ang SignatureDoesNotMatch. Lalabas ito sa worker log kahit mukhang maayos pa rin ang web interface. Ang pagpapanatili ng mga value na ito sa isang env file sa halip na sa tracked compose file ang pattern na saklaw sa env file at secret ng Docker Compose.
I-pin ang mga image tag bago magsimula
Ginagamit ng shipped file ang docker.langfuse.com/langfuse/langfuse:4 at docker.langfuse.com/langfuse/langfuse-worker:4. Nagbabago ang mga tag na iyon. Awtomatikong pinapatakbo ng Langfuse ang Postgres at ClickHouse migration sa pagsisimula. Dahil dito, ang isang karaniwang docker compose pull pagkalipas ng ilang buwan ay maaaring maging hindi planadong schema migration sa database na hindi mo na-back up noong umagang iyon. I-pin ang dalawang image sa isang release gamit ang docker-compose.override.yml. Ima-merge ng Compose ang file na ito sa shipped file, kaya hindi sasalungat ang susunod na git pull sa iyong mga edit. Ipinapublish din ang parehong image sa Docker Hub. Doon kinukuha ng override sa ibaba ang mga ito.
services:
langfuse-web:
image: docker.io/langfuse/langfuse:4.72.0
langfuse-worker:
image: docker.io/langfuse/langfuse-worker:4.72.0Ang Version 4.3.1 ang kasalukuyang 4.3 release noong August 2026. Mabilis ang paglabas ng mga release mula noon. Ang v4.56.0 ang pinakabagong release sa GitHub noong October 11, 2026. Ginagamit ng override sa itaas ang v4.72.0, ang pinakabagong release sa GitHub noong October 31, 2026. Suriin ang GitHub releases page ng proyekto. I-pin ang kasalukuyang version sa araw ng deployment, pagkatapos ay sadyang baguhin ang number na iyon kapag kailangan. Dapat ding bigyan ng parehong treatment ang ilang storage image sa shipped file dahil nagbabago rin ang mga tag ng mga ito. Ang postgres:17, na default ng POSTGRES_VERSION variable, at ang redis:7 ay sumusunod sa major version. Gumagamit na ngayon ang shipped file ng exact version tag para sa docker.io/clickhouse/clickhouse-server, kaya naka-pin ang eksaktong ClickHouse version. Hindi lang ito nalalapat sa Langfuse: isang self-hosted na openGym workout tracker ang gumagamit ng maliit na bahagi ng stack na ito ngunit nangangailangan pa rin ng pinangalanang git tag. Ang anumang awtomatikong nagmi-migrate ng sariling database sa pagsisimula ay maaaring gawing schema change ang isang karaniwang pull.
Paandarin ito.
docker compose up -d
docker compose ps
docker compose logs -f langfuse-workerPinapatakbo ang mga migration sa unang boot. Maghintay ng dalawa o tatlong minuto bago asahang may sasagot na serbisyo. Ila-log ng web container ang Ready kapag handa na ito. Dapat maglista ang docker compose ps ng anim na service na nasa state na running. Kapag paulit-ulit na nagre-restart ang isang container, nasa log nito ang dahilan. Inia-apply ang ClickHouse migration kapag nagsisimula ang web container. Kaya lalabas ang maling CLICKHOUSE_MIGRATION_URL sa docker compose logs langfuse-web, hindi sa worker log na mino-monitor mo. Ginagamit ng variable na iyon ang ClickHouse native protocol sa port 9000, hindi ang HTTP port 8123. Kapag itinuro mo ito sa 8123, mabibigo ang startup migration ng web container. Pinapatakbo ng worker ang mas mabagal na background migration. Kaya sa log nito makikita ang report ng mga migration na iyon.
Suriin ang health mula mismo sa server.
curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/readyPinatutunayan lamang ng isang karaniwang /api/public/health call na aktibo ang API process. Bilang default, hindi nito sinusuri ang database. Ang failIfDatabaseUnavailable=true form ang dapat mong gamitin para sa monitoring. Nagbabalik ito ng 503 kapag hindi maabot ang database. Nagbabalik ang /api/public/ready ng 200 kapag handa nang tumanggap ng traffic ang web container, at 500 kapag inutusan na itong mag-shutdown. Karaniwang HTTP check ang dalawang ito. Kaya maaaring i-monitor ng isang Uptime Kuma status page ang mga ito at ipaalam na down ang stack bago pa ito mapansin ng iyong mga agent.
Ilagay ang TLS sa unahan at isara ang mga karagdagang port
Inilalabas ng kasamang compose file ang 3000:3000 para sa web container at ang 9090:9000 para sa MinIO. Pareho silang nagbi-bind sa lahat ng interface. Sa isang public IP, nangangahulugan ito na sinumang mag-scan sa port 3000 ay makararating sa iyong sign-up page, at sinumang mag-scan sa 9090 ay makakakonekta sa bucket na naglalaman ng iyong mga raw prompt.
Hindi sapat ang firewall rule para maisara ang mga ito. Gumagawa ang Docker ng sarili nitong DNAT rules sa nat table. Sinusuri ang mga rule na ito bago pa makita ng filter rules ng ufw ang packet, kaya iniiwang bukas ng ufw deny 3000 ang published port. Sapat na madalas mangyari ang problemang ito kaya mayroon itong sariling gabay: bakit nalalampasan ng Docker published ports ang ufw. Sa halip, mag-bind sa loopback sa iyong override file. Gamitin ang !override sa Docker Compose 2.24.4 o mas bago upang palitan ang published ports; kapag plain list ang ginamit, mina-merge lamang ito sa orihinal na bindings.
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"Dapat eksaktong public address ang NEXTAUTH_URL, kasama ang scheme, dahil binubuo ng login flow ang callback URL mula sa value na iyon. Iwan itong http://localhost:3000 sa likod ng HTTPS proxy, at ipapadala ng sign-in round trip ang browser sa address na hindi nito maaabot.
Ngayon, ituro ang reverse proxy sa 127.0.0.1:3000 at hayaan itong humawak ng certificate. Para sa Traefik sa parehong Compose project, mag-route sa langfuse-web:3000 sa pamamagitan ng Compose network gamit ang mga label na inilalarawan sa pagpapatakbo ng maraming app sa likod ng isang Traefik reverse proxy. Pareho ang ginagawa ng Caddy sa dalawang linya kung Langfuse lamang ang tumatakbo sa server. I-verify gamit ang curl -sI https://langfuse.example.com/api/public/ready, pagkatapos ay tiyakin mula sa ikalawang machine na hindi makakakonekta ang curl http://YOUR_IP:3000.
May isang paalala tungkol sa MinIO. Nagbibigay ang Langfuse ng presigned URLs na tumuturo sa S3 endpoint na iyon, kapwa para sa mga SDK na nag-a-upload ng media at para sa browser na naglo-load nito. Kaya kung gumagamit ka ng multi-modal traces na may mga image o audio, hindi makakapag-upload ang loopback-only MinIO ng mga attachment mula sa ibang machine, at hindi rin mai-load ng browser mo ang mga ito. Basahin ang blob storage configuration page bago ito i-proxy, dahil kailangang tumugma ang endpoint na inilalagay sa presigned URL, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, sa endpoint na inilalathala mo. Hindi naaapektuhan ang plain text traces.
Gumawa ng account sa unang pagbisita, pagkatapos ay panatilihing iyo ang instance. Itakda ang AUTH_DISABLE_SIGNUP=true kapag mayroon ka nang account, upang hindi na makapag-register ang estrangherong makararating sa page. Mayroon ding LANGFUSE_ALLOWED_ORGANIZATION_CREATORS ang Langfuse, na naglilimita kung sino ang maaaring gumawa ng mga organisation, ngunit Enterprise Edition feature ito at magkakabisa lamang kapag may license key. Kung gumagamit ka na ng Authentik bilang sarili mong identity provider, tumatanggap ang Langfuse ng standard OIDC connection. Dahil dito, sumasabay ang mga account sa iba mo pang app sa paglikha at pagtanggal ng mga ito, sa halip na manatili sa password list na ang server na ito lamang ang nakaaalam.
Ipadala ang iyong unang trace
Gumawa ng project sa web interface at kopyahin ang public at secret keys nito mula sa project settings. Nagbabasa ang Python SDK ng tatlong environment variable.
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"LANGFUSE_BASE_URL ang variable name sa SDK v4, na inilabas noong March 2026. Ginagamit naman ng mas lumang code at mga lumang guide ang LANGFUSE_HOST. Kung napupunta ang iyong traces sa Langfuse Cloud sa halip na sa sarili mong server, sanhi ito ng hindi naka-set na base URL, dahil ang default ay tumuturo sa hosted instance.
Nangangailangan ang kasalukuyang Python SDK v5 ng Python 3.11 o mas bago at self-hosted Langfuse v4.59.0 o mas bago. Natutugunan ito ng naka-pin na server sa itaas.
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()Binubuksan ng @observe decorator ang isang observation sa paligid ng function, kinukuha ang mga argument nito at return value, at inilalagay ito sa ilalim ng kasalukuyang aktibong observation. Ang AnthropicInstrumentor ay ang OpenTelemetry instrumentation para sa Anthropic client. Ginagawa nitong generation ang bawat messages.create call na naglalaman ng model name, token usage, at latency, nang walang kailangang baguhin sa call site.
Dalawang call ang gumagawa ng checking para sa iyo. Nagbabalik ang langfuse.auth_check() ng False kapag mali ang keys o base URL, kaya mas mabilis mong matutukoy ang problema kaysa mag-isip kung bakit walang laman ang dashboard. Hinaharangan naman ng langfuse.flush() ang proseso hanggang maipadala ang mga naka-queue na span. Kailangan ito ng mga short-lived process dahil nagba-batch sa background ang SDK, at kapag agad nag-exit ang script, kasama nitong nawawala ang batch na hindi pa naipapadala. Kung buong team ang nagpapadala ng traces at hindi isang script lamang, isang beses lang itakda ang tatlong variable na iyon sa gateway na ginagamit na ng mga agent ng lahat, sa halip na sa shell ng bawat tao. Ganito napapanatiling instrumented ang mga run ng bawat kasamahan sa pamamagitan ng isang self-hosted OneCLI harness, habang nananatili sa isang lugar ang mga key.
Bakit patuloy na lumalaki ang ClickHouse?
Ang traces ang pinakamabilis lumaking data sa karamihan ng self-hosted deployment. Sa bawat pagtakbo ng agent, may isang row na sinusulat para sa bawat step. Buong iniimbak ang inputs at outputs. Kaya ang isang madaldal na agent na may mahahabang prompt ay maaaring lumikha ng mas maraming bytes bawat araw kaysa sa application na mino-monitor nito. Kapag pinabayaan, mapupuno ng ClickHouse ang disk. Kapag puno ang disk, hihinto ang ingestion sa halip na bumagal lamang.
Dalawang magkahiwalay na bagay ang lumalaki rito. Magkahiwalay din ang kailangan nilang ayusin.
Ang una ay ang sarili mong trace data. Ang retention setting ang solusyon dito. Sa isang self-hosted instance, Enterprise Edition feature ang data retention at nangangailangan ito ng license key. Kung walang license key, walang katapusang pinananatili ng Langfuse ang traces, observations, scores, at media. Kaya dapat sapat ang laki ng disk para rito, at umasa sa disk alert sa dulo ng seksyong ito. Kapag may license, buksan ng mga project owner at admin ang project settings at magtakda ng data retention period sa bilang ng araw. Tumatanggap ang Langfuse ng minimum na 3 araw. Bawat gabi, pumipili ang isang job ng mga trace, observation, score, at media asset na mas luma sa itinakdang window at dine-delete ang mga ito mula sa ClickHouse at blob storage, maliban sa media na nauugnay sa mga naka-save na dataset item. Kailangan ng job ang DeleteObject permission sa bucket. Mayroon na nito ang MinIO root credentials sa default compose file. Permanente ang deletion. Kaya mag-configure muna ng blob storage export kung kailangan mo ng pangmatagalang history. Huwag manu-manong magsulat ng TTL clause sa sariling tables ng Langfuse. Ang retention job ang nagpapanatiling nakaayon sa isa’t isa ang ClickHouse at ang bucket. Kapag manual TTL ang ginamit, isang side lamang ang made-delete.
Piliin ang window batay sa aktuwal mong paggamit. Sa data na ilang araw pa lamang ang edad ginagawa ang cost at quality review, hindi sa data na ilang buwan na. Makatuwirang panimula ang 30 araw para sa maliit na team. Sapat na ang 14 araw kung trace lamang ang binubuksan mo kapag may nasira.
Ang ikalawa ay ang sariling system log tables ng ClickHouse. Nakapagtataka ito sa maraming tao dahil patuloy na lumalaki ang disk kahit naka-configure na ang retention. Sinusulatan ng ClickHouse ang trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log at latency_log para sa sarili nitong diagnostics. Wala silang kasamang TTL, at hindi kailanman binabasa ng Langfuse ang mga ito. Alamin muna kung saan talaga napunta ang disk space.
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
)Patakbuhin ito gamit ang docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Kung malapit sa itaas ng listahan ang system tables, i-disable ang mga ito gamit ang config overlay. Pinagsasama ng ClickHouse ang bawat file sa /etc/clickhouse-server/config.d/ sa ibabaw ng main config nito sa pagsisimula.
<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>I-mount ito at i-restart ang ClickHouse.
services:
clickhouse:
volumes:
- ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:roHihinto nito ang mga bagong write. Mananatili sa disk ang mga row na naroon na. Kaya bawiin ang space nang tahasan gamit ang DROP TABLE IF EXISTS system.trace_log, at gawin din ito para sa bawat table na inalis mo. Kung mas gusto mong panatilihin ang diagnostics, ang alternatibo ay magtakda ng agresibong TTL sa bawat table sa halip na remove="1". Ipinaliwanag ito nang detalyado sa Langfuse scaling docs. Nalalapat lamang ang mga TTL directive na iyon kapag unang nilikha ang isang system table. Kaya para sa kasalukuyang installation, ipinapakita rin ng parehong docs kung paano i-retrofit ang mga table.
May isa pang table na dapat mong malaman. Tinutunton ng blob_storage_file_log ang mga event file na ina-upload sa iyong bucket. Kung nagtakda ka rin ng lifecycle policy sa bucket, magtakda ng katugmang TTL sa table upang hindi magkahiwalay ang expiration ng mga ito.
ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;Maglagay din ng plain df -h alert sa data disk. Hindi pantay-pantay ang paglaki ng traces. Lumalaki ang mga ito kapag nag-release ka ng bagong agent. Hindi dapat ingestion failure ang unang senyales nito.
Mag-backup ng Postgres at ClickHouse
May tatlong bahagi ang Langfuse backup. Nasa Postgres ang mga user, organisasyon, project, at API key. Nasa ClickHouse ang mga trace. Nasa MinIO ang raw event. Kung Postgres lang ang ire-restore mo, magkakaroon ka ng gumaganang login pero walang history. Kung ClickHouse lang ang ire-restore mo, magkakaroon ka ng history na walang makakapag-login para makita. Hindi natatangi sa Langfuse ang ganitong paghahati. May ganito ring setup ang self-hosted Chatwoot support desk, kung saan kapag gumawa ka ng Postgres dump nang hindi isinama ang uploads directory, mare-restore ang mga conversation pero mawawala ang lahat ng attachment.
Plain pg_dump ang Postgres, at ito ang ginagamit ng Langfuse backup docs para sa Docker install.
docker compose exec -T postgres pg_dump -U postgres postgres \
| gzip > langfuse-pg-$(date +%F).sql.gzMas kailangang mag-ingat sa ClickHouse dahil hindi consistent ang backup kapag kinopya ang live data directory habang tumatakbo ang mga merge. Ang simpleng paraan sa isang server ay ihinto ang container at i-archive ang 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 clickhouseGamitin ang volume name na ipinapakita ng docker volume ls, hindi ang nakasulat sa YAML. Idinedeklara ng file ang langfuse_clickhouse_data, at nilalagyan ito ng Compose ng project name bilang prefix. Kaya ang clone sa directory na tinatawag na langfuse ay gumagawa ng langfuse_langfuse_clickhouse_data. Kapag mali ito, gagawa ang docker run ng bagong walang-lamang volume nang walang error, at walang laman ang archive mo.
Ina-upload ng Langfuse ang raw event data sa bucket sa bawat ingestion request, at binabasa itong muli para i-retry ang mga nabigong ingestion job. Kaya kung panandalian mong ihihinto ang ClickHouse, kadalasan ay magre-retry ang worker pagkatapos. Gawin ito sa oras na kaunti ang traffic at panatilihing maikli ang downtime. Para sa mas abalang instance, ang sariling BACKUP DATABASE default TO S3(...) statement ng ClickHouse ay gumagawa ng consistent backup nang hindi ihihinto ang server. Ang MinIO ang ikatlong bahagi, at sapat na rito ang mc mirror o MinIO replication papunta sa bucket sa ibang server. Anuman ang gawin mong backup, ilipat ito palabas ng server. Iyan ang gamit ng encrypted restic backups sa isang VPS.
Nasa Redis ang queue at cache. Kapag nawala ito, mawawala ang mga naka-queue na job kahit nasa bucket pa ang mga raw event file.
Totoo ang consistency caveat at dapat itong sabihin nang malinaw. Magkahiwalay na oras ginagawa ang dump ng Postgres at ClickHouse, kaya maaaring magkaroon ang restore ng project row na walang trace, o ng trace na kabilang sa project na wala na. Kinakaya ito ng Langfuse, pero gawin ang dalawang dump nang magkalapit ang oras at sa panahong kaunti ang traffic. Ang event bucket ang tunay na safety net dahil ina-upload dito ng Langfuse ang raw event data sa bawat ingestion request.
Mag-restore kahit isang beses sa scratch stack. Sa ganitong paraan, matutuklasan mo agad kung mali ang volume name, sa halip na sa oras ng outage pa.
Mga unang dapat tingnan
May apat na bagay na dapat mong unahin sa unang linggo.
- Gastos bawat trace. Kinukuwenta ng Langfuse ang gastos batay sa model name at token usage, kaya i-sort ang mga trace ayon sa gastos at basahin nang buo ang pinakamahal. Karaniwan, lumaki ang prompt: maaaring buong dokumento ang ipinasa sa context, o conversation history na walang naglilimita sa haba. Kapag nakikita mo na ito, nagiging engineering task sa halip na hula ang pagkontrol sa gastos ng AI agent mo.
- Hati ng token usage sa input at output. Marami at mura ang input tokens, kaunti at mahal ang output tokens, at mas mura pa ang cached input. Ipinaliliwanag din sa kung paano binibilang ang token usage ng Claude Code ang parehong accounting, at naaangkop ito sa anumang agent na ikaw mismo ang sumusulat.
- Latency percentiles. Itinatago ng median ang problema. Sa p95 at p99 karaniwang lumilitaw ang mga timeout, at sa loob ng agent loop, ang mabagal na tool call sa p95 ay napaparami ayon sa bilang ng iterations.
- Mga nabigong tool call. I-filter ang observations ayon sa level
ERROR. Ang tool na 5% ng oras ay nabibigo ay maaaring hindi makita sa pinagsama-samang success rate, ngunit malinaw itong makikita sa mga trace, kung saan namo-monitor mong inuulit ng model ang request at pagkatapos ay gumagastos ng tokens upang malampasan ang problema.
Itakda ang retention window at piliin ang dashboard na susuriin mo bawat linggo sa parehong araw ng pag-deploy. Ang observability tool na walang nagbubukas ay database na kalaunan ay pupunuin ang disk.
FAQ
Gaano karaming memory ang kailangan ng isang self-hosted Langfuse?
Maglaan ng 4 CPU core at 16 GiB na memory, na siyang inirerekomenda ng Langfuse Docker Compose guide para sa isang virtual machine, at humigit-kumulang 100 GiB na storage. Ang mga inilathalang minimum requirement ng bawat component ay 8 GiB para sa ClickHouse at tig-4 GiB para sa mga web at worker container. Nakalista rin sa parehong page ang 4 GiB para sa Postgres, 1.5 GiB para sa Redis, at 4 GiB para sa MinIO. Kaya umaabot sa 25.5 GiB ang kabuuan ng anim na component, na mas mataas kaysa sa 16 GiB na rekomendasyon para sa Compose.
Bakit patuloy na napupuno ang ClickHouse disk kahit nagtakda na ako ng data retention?
Ang retention setting ay para lamang sa sariling data ng Langfuse. Hiwalay na nagsusulat ang ClickHouse ng mga diagnostic table na trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log at latency_log, at walang TTL ang mga ito. I-run ang query na system.parts na naka-group ayon sa table para makita kung alin ang pinakamalaki. Pagkatapos, i-disable ang mga hindi ginagamit na table gamit ang remove="1" entry sa isang file sa ilalim ng /etc/clickhouse-server/config.d/, i-restart ang ClickHouse, at i-drop ang mga kasalukuyang table upang mabawi ang espasyong nagamit na.
Ano ang minimum na data retention period sa Langfuse?
Tatlong araw. Itinatakda ang retention bawat project sa project settings o sa pamamagitan ng Organization Management API. Gabi-gabing dine-delete ng isang job ang mga trace, observation, score at media asset na mas luma sa itinakdang window mula sa ClickHouse at blob storage, maliban sa media na nauugnay sa mga naka-save na dataset item. Sa self-hosted instance, feature ito ng Enterprise Edition at nangangailangan ng license key. Kung walang license key, walang takdang panahon ang pag-iingat ng data. Hindi na maibabalik ang na-delete, kaya mag-configure muna ng blob storage export kung kailangan mo ng history na lampas sa window na iyon.
Kailangan ko bang mag-back up ng Postgres at ClickHouse?
Oo, dahil magkaibang data ang hawak ng mga ito. Hawak ng Postgres ang mga user, organisation, project at API key, habang hawak ng ClickHouse ang mismong trace data. Kapag Postgres lang ang na-restore, magkakaroon ka ng instance na maaari mong pag-loginan pero walang laman. I-back up din ang MinIO bucket dahil naglalaman ito ng mga raw event na sine-save ng Langfuse pagdating ng mga ito. Ito ang pinakamalapit sa source of truth sa stack.
Maaari ko bang ituro ang isang umiiral na OpenTelemetry setup sa self-hosted Langfuse?
Oo. Nakabatay ang Langfuse v4 at ang kasalukuyan nitong SDK sa OpenTelemetry, at direktang nag-e-export rito ang Anthropic at OpenAI OTel instrumentation. Sa Python, i-run ang pip install langfuse opentelemetry-instrumentation-anthropic, tawagin ang AnthropicInstrumentor().instrument() nang isang beses sa startup, at itakda ang LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY at LANGFUSE_BASE_URL sa sarili mong host. Kumpirmahin gamit ang langfuse.auth_check() bago maghanap ng nawawalang dashboard.