Langfuse zelf hosten op een eigen VPS: handleiding
Leer hoe u Langfuse veilig zelf host op uw eigen VPS. Wij behandelen de minimale resourcevereisten, vaste image tags, TLS-configuratie en ClickHouse retentie-instellingen.
Waarom zou u een AI-agent überhaupt traceren
U host Langfuse zelf om inzicht te krijgen in wat uw agent daadwerkelijk heeft uitgevoerd tijdens een run. Langfuse is een open-source tool voor observability van LLM's (large language models). Het registreert elke prompt, elk modelantwoord, elke tool-aanroep en elke token, en groepeert deze vervolgens onder één trace die u kunt openen en inzien. Door dit op uw eigen VPS te draaien, verlaten deze prompts nooit een server die u beheert.
De reden om dit te doen is duidelijk. U kunt een probleem met kosten of kwaliteit niet oplossen als u het niet kunt zien. Een factuur van een provider vertelt u dat dinsdag vier keer zoveel kostte als maandag. Een trace vertelt u welke agent-run de oorzaak was, welke prompt groeide naar 40.000 tokens en welke retry-loop negen keer draaide voordat deze opgaf. De factuur geeft u het getal. De trace geeft u de code die het getal heeft geproduceerd.
In deze handleiding worden drie termen gebruikt. Een trace is één end-to-end run van uw agent. Een observation is één stap binnen die run: een span voor reguliere code, een generation voor een aanroep naar een model. Een score is een getal dat aan een trace wordt gekoppeld, afkomstig van een menselijke beoordeling of een geautomatiseerde evaluator. Langfuse ondersteunt OpenTelemetry (OTel), de leverancieronafhankelijke standaard voor distributed tracing, waardoor instrumentatie die u al heeft hiernaar kan verwijzen.
Wat self-hosting Langfuse daadwerkelijk uitvoert
Langfuse v4 is niet één container. Het bestaat uit twee applicatiecontainers en vier opslagservices, en op een enkele VPS draaien alle zes op uw machine.
langfuse-webbedient de webinterface en de ingestion API.langfuse-workerverwerkt de wachtrij op de achtergrond. Deze parseert ingestion-batches, berekent kosten en voert de dagelijkse retentietaken uit.- Postgres bevat transactionele gegevens zoals gebruikers, organisaties, projecten, API-keys en prompts.
- ClickHouse bevat de trace-data zelf, oftewel observaties en scores. Dit is een kolomgeoriënteerde database die is gebouwd voor analytische queries, waardoor een dashboard met honderd miljoen rijen nog steeds snel antwoord geeft.
- Redis fungeert als de wachtrij en de cache tussen de webinterface en de worker.
- MinIO biedt S3-compatibele objectopslag op de machine. Het bevat elk onbewerkt inkomend event plus alle media die u toevoegt.
Langfuse publiceert de minimale resources voor elke component die het uitvoert. De tabel toont de drie componenten die het werk verrichten.
De gegevens achter deze grafiek
[
{
"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 alleen al vraagt om 8 GiB aan geheugen. De webcontainer en de worker vragen elk om 4 GiB. Dat zijn de gepubliceerde ondergrenzen voor de 3 componenten in de tabel. Dezelfde pagina vermeldt Postgres op 4 GiB, Redis of Valkey op 1,5 GiB en MinIO op 4 GiB, dus de minima voor alle zes tellen op tot 25,5 GiB. De Docker Compose-handleiding van het project zelf adviseert minimaal 4 cores, 16 GiB aan geheugen en ongeveer 100 GiB aan opslag voor een enkele machine. Dat is minder dan de som van de ondergrenzen van de componenten, dus beschouw 16 GiB als het absolute minimum voor een gedeelde Compose-machine, niet als extra ruimte.
Probeer dit niet op een abonnement van 2 GiB. ClickHouse start op, accepteert een tijdje schrijfacties, maar crasht vervolgens tijdens een achtergrond-merge, omdat een merge grote delen van een tabel in het geheugen laadt. U zult zien dat docker compose ps de clickhouse-container rapporteert als restarting, dmesg een regel bevat zoals Out of memory: Killed process 1234 (clickhouse-serv), en elk Langfuse-dashboard een 500-foutmelding geeft. Onder lichtere druk weigert ClickHouse de query en logt DB::Exception: Memory limit (total) exceeded. Zestien is het getal om voor te plannen. Als dezelfde VPS ook andere taken moet uitvoeren, reserveer daar dan apart budget voor, want zelfs een relatief lichte stack zoals een self-hosted AFFiNE-workspace vereist zijn eigen gigabytes en ClickHouse geeft deze niet terug.
Langfuse implementeren met Docker Compose
Kloon de repository. De stack, de configuratie en de standaardomgeving bevinden zich in de bijbehorende docker-compose.yml.
git clone https://github.com/langfuse/langfuse.git
cd langfuseElke waarde die u moet wijzigen, is in dat bestand gemarkeerd als # CHANGEME. Genereer eerst de drie applicatiegeheimen.
openssl rand -base64 32 # NEXTAUTH_SECRET
openssl rand -base64 32 # SALT
openssl rand -hex 32 # ENCRYPTION_KEYENCRYPTION_KEY moet 256 bits zijn, geschreven als 64 hexadecimale tekens; dit is precies wat openssl rand -hex 32 genereert. Het versleutelt gevoelige waarden in rust, inclusief alle LLM-provider-keys die u in de instantie opslaat. Wijzig dit niet nadat er gegevens bestaan, aangezien die rijen dan niet meer ontsleuteld kunnen worden; beschouw het vanaf de eerste opstart als permanent. SALT wordt gebruikt voor het hashen van uw Langfuse API-keys; het wijzigen hiervan maakt alle keys die uw agents al gebruiken ongeldig.
Stel vervolgens POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH en MINIO_ROOT_PASSWORD in. Het MinIO-wachtwoord komt op vier plaatsen voor: eenmaal als MINIO_ROOT_PASSWORD, en daarna nogmaals als LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY en LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Als u er een mist, weigert MinIO de client met SignatureDoesNotMatch, wat in het logboek van de worker verschijnt terwijl de webinterface er nog steeds gezond uitziet. Het bijhouden van deze waarden in een env-bestand in plaats van in het versiebeheerde compose-bestand is de methode die wordt behandeld in Docker Compose env-bestanden en secrets.
Zet de image-tags vast voordat u begint
Het meegeleverde bestand gebruikt docker.langfuse.com/langfuse/langfuse:4 en docker.langfuse.com/langfuse/langfuse-worker:4. Die tags veranderen. Langfuse voert zijn Postgres- en ClickHouse-migraties automatisch uit bij het opstarten, dus een routine-docker compose pull maanden later wordt een ongeplande schema-migratie op een database waarvan u die ochtend geen back-up hebt gemaakt. Zet beide vast op één release in een docker-compose.override.yml, die Compose bovenop het meegeleverde bestand samenvoegt, zodat een latere git pull uw wijzigingen nooit overschrijft. Dezelfde images worden gepubliceerd op Docker Hub, waar de onderstaande override ze vandaan haalt.
services:
langfuse-web:
image: docker.io/langfuse/langfuse:4.72.0
langfuse-worker:
image: docker.io/langfuse/langfuse-worker:4.72.0Versie 4.3.1 was de huidige 4.3-release in augustus 2026. Releases zijn sindsdien snel gevolgd en v4.56.0 was de nieuwste op GitHub op 11 oktober 2026. De bovenstaande override gebruikt v4.72.0, de nieuwste op GitHub op 31 oktober 2026. Controleer de GitHub-releasespagina van het project, zet vast wat op de dag van implementatie actueel is en wijzig dat versienummer vervolgens bewust. Sommige opslag-images in het meegeleverde bestand verdienen dezelfde behandeling, omdat hun tags ook veranderen. postgres:17 (de standaardwaarde van een POSTGRES_VERSION-variabele) en redis:7 volgen een hoofdversie. Het meegeleverde bestand gebruikt nu een exacte versietag voor docker.io/clickhouse/clickhouse-server, waarmee een specifieke ClickHouse-versie wordt vastgezet. Die regel is niet specifiek voor Langfuse: een zelfgehoste openGym workout tracker draait een fractie van deze stack en vereist nog steeds een benoemde git-tag, omdat alles wat bij het opstarten de eigen database migreert, een routine-pull kan veranderen in een schema-wijziging.
Start de stack.
docker compose up -d
docker compose ps
docker compose logs -f langfuse-workerDe eerste opstart voert de migraties uit, dus wacht twee of drie minuten voordat er antwoord komt. De webcontainer logt Ready zodra deze actief is. docker compose ps zou zes services in de status running moeten weergeven. Als een container in een lus herstart, bevat het logboek de reden. ClickHouse-migraties worden toegepast wanneer de webcontainer start, dus een foutieve CLICKHOUSE_MIGRATION_URL verschijnt in docker compose logs langfuse-web, niet in het worker-logboek dat u monitort. Die variabele gebruikt het eigen ClickHouse-protocol op poort 9000, niet de HTTP-poort 8123; het verwijzen naar 8123 verstoort de opstartmigraties van de webcontainer. De worker voert de tragere achtergrondmigraties uit, dus in dat logboek worden die gerapporteerd.
Controleer de status vanaf de server zelf.
curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/readyEen eenvoudige /api/public/health-aanroep bewijst alleen dat het API-proces actief is, omdat dit standaard de database niet controleert. De failIfDatabaseUnavailable=true-vorm is de moeite waard om op te monitoren; deze retourneert 503 wanneer de database onbereikbaar is. /api/public/ready retourneert 200 wanneer de webcontainer klaar is om verkeer te ontvangen, en 500 zodra de opdracht tot afsluiten is gegeven. Beide zijn standaard HTTP-checks, dus een Uptime Kuma-statuspagina kan deze monitoren en u waarschuwen dat de stack offline is voordat uw agents dat doen.
Plaats TLS aan de voorzijde en sluit de extra poorten
Het meegeleverde compose-bestand publiceert 3000:3000 voor de webcontainer en 9090:9000 voor MinIO. Beide binden op elke interface. Op een publiek IP-adres betekent dit dat iedereen die poort 3000 scant, uw aanmeldpagina bereikt, en iedereen die poort 9090 scant, communiceert met de bucket die uw ruwe prompts bevat.
Een firewallregel alleen sluit deze poorten niet. Docker schrijft zijn eigen DNAT-regels naar de nat-tabel, en deze worden geëvalueerd voordat de filterregels van ufw het pakket ooit zien. Daarom laat ufw deny 3000 de gepubliceerde poort openstaan. Dit probleem komt zo vaak voor dat er een eigen handleiding voor is: waarom Docker gepubliceerde poorten ufw omzeilen. Bind in uw override-bestand in plaats daarvan op loopback. Gebruik !override met Docker Compose 2.24.4 of nieuwer om de gepubliceerde poorten te vervangen; een eenvoudige lijst wordt namelijk samengevoegd met de oorspronkelijke bindingen.
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 moet het exacte publieke adres zijn, inclusief het schema, omdat het inlogproces de callback-URL op basis van die waarde opbouwt. Laat u dit als http://localhost:3000 achter een HTTPS-proxy, dan stuurt de inlog-roundtrip de browser naar een locatie die niet bereikbaar is.
Wijs nu een reverse proxy naar 127.0.0.1:3000 en laat deze het certificaat beheren. Voor Traefik in hetzelfde Compose-project routeert u naar langfuse-web:3000 via het Compose-netwerk met behulp van de labels die worden behandeld in meerdere applicaties draaien achter één Traefik reverse proxy. Caddy doet hetzelfde werk in twee regels als Langfuse de enige applicatie op de server is. Controleer dit met curl -sI https://langfuse.example.com/api/public/ready en bevestig vervolgens vanaf een tweede machine dat curl http://YOUR_IP:3000 geen verbinding kan maken.
Eén kanttekening bij MinIO: Langfuse verstrekt presigned URL's die naar dat S3-eindpunt wijzen, zowel aan SDK's die media uploaden als aan uw browser die deze laadt. Als u dus multimodale traces gebruikt die afbeeldingen of audio bevatten, betekent een MinIO die alleen op loopback luistert dat deze bijlagen niet vanaf andere machines kunnen worden geüpload of in uw browser kunnen worden geladen. Lees de configuratiepagina voor blob-opslag voordat u deze proxied, omdat het eindpunt dat in de presigned URL wordt geschreven, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, moet overeenkomen met wat u publiceert. Traces met platte tekst worden hierdoor niet beïnvloed.
Maak uw account aan bij het eerste bezoek en houd de instantie vervolgens voor uzelf. Stel AUTH_DISABLE_SIGNUP=true in zodra uw account bestaat, zodat een vreemde die de pagina bereikt zich niet kan registreren. Langfuse heeft ook LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, wat beperkt wie organisaties mag aanmaken, maar dit is een Enterprise Edition-functie en is alleen van kracht met een licentiesleutel. Als u al Authentik als uw eigen identiteitsprovider gebruikt, accepteert Langfuse een standaard OIDC-verbinding. Hierdoor worden accounts beheerd in lijn met uw overige applicaties in plaats van in een wachtwoordenlijst die alleen op deze server bekend is.
Verstuur uw eerste trace
Maak een project aan in de webinterface en kopieer de public en secret keys uit de projectinstellingen. De Python SDK leest drie omgevingsvariabelen.
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"LANGFUSE_BASE_URL is de variabelenaam in SDK v4, die in maart 2026 werd uitgebracht. Oudere code en oudere handleidingen gebruiken LANGFUSE_HOST. Als uw traces op Langfuse Cloud terechtkomen in plaats van op uw server, is een niet-ingestelde base URL de oorzaak, omdat de standaardwaarde naar de gehoste instantie wijst.
De huidige Python SDK v5 vereist Python 3.11 of hoger en self-hosted Langfuse v4.59.0 of hoger, waar de hierboven vastgepinde server aan voldoet.
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()De @observe-decorator opent een observatie rondom de functie, legt de argumenten en de retourwaarde vast, en nest deze onder de observatie die al actief is. AnthropicInstrumentor is de OpenTelemetry-instrumentatie voor de Anthropic-client, en deze verandert elke messages.create-aanroep in een generatie die de modelnaam, het tokenverbruik en de latentie bevat, zonder wijzigingen op de aanroeplocatie.
Twee aanroepen voeren de controle voor u uit. langfuse.auth_check() retourneert False bij ongeldige keys of een onjuiste base URL, wat sneller is dan u afvragen waarom het dashboard leeg is. langfuse.flush() blokkeert totdat de wachtrij met spans is verzonden; kortstondige processen hebben dit nodig, omdat de SDK op de achtergrond batches verwerkt en een script dat direct afsluit zijn onverzonden batch meeneemt. Als een heel team traces verstuurt in plaats van één script, stel die drie variabelen dan eenmalig in op de gateway waar alle agents van collega's al doorheen lopen, in plaats van in de shell van elke persoon. Dit is hoe een self-hosted OneCLI-harness ervoor zorgt dat de runs van elke collega geïnstrumenteerd blijven terwijl de keys op één plek blijven.
Waarom blijft ClickHouse groeien?
Traces zijn de snelst groeiende gegevens die de meeste mensen zelf hosten. Elke agent-run schrijft één rij per stap, en inputs en outputs worden volledig opgeslagen. Een actieve agent met lange prompts produceert daardoor per dag veel meer bytes dan de applicatie die hij monitort. Als u niets doet, raakt de schijf van ClickHouse vol. Een volle schijf stopt de gegevensopname volledig in plaats van deze alleen te vertragen.
Er groeien hier twee afzonderlijke zaken, en deze vereisen twee afzonderlijke oplossingen.
Het eerste is uw eigen trace-data; de oplossing hiervoor is de retentie-instelling. Bij een zelf-gehoste instantie is dataretentie een Enterprise Edition-functie waarvoor een licentiesleutel vereist is. Zonder licentie bewaart Langfuse traces, observaties, scores en media voor onbepaalde tijd. Zorg in dat geval voor voldoende schijfruimte en vertrouw op de schijfwaarschuwing aan het einde van dit gedeelte. Met een licentie kunnen projecteigenaren en beheerders in de projectinstellingen een bewaartermijn in dagen instellen. Langfuse accepteert een minimum van 3 dagen. Een nachtelijke taak selecteert vervolgens traces, observaties, scores en media-assets die ouder zijn dan dat venster en verwijdert deze uit ClickHouse en uit de blob-opslag, met uitzondering van media die gekoppeld zijn aan opgeslagen dataset-items. De taak heeft DeleteObject-rechten nodig op de bucket; de MinIO root-inloggegevens in het standaard compose-bestand beschikken hier al over. Verwijdering is permanent, dus configureer eerst een export naar blob-opslag als u langetermijnhistorie nodig heeft. Schrijf niet handmatig TTL-clausules op de eigen tabellen van Langfuse: de retentietaak zorgt ervoor dat ClickHouse en de bucket synchroon blijven; een handmatige TTL verwijdert gegevens slechts aan één kant.
Kies het venster op basis van wat u daadwerkelijk gebruikt. Kosten- en kwaliteitsbeoordelingen vinden plaats op data van enkele dagen oud, niet van maanden oud. Dertig dagen is een redelijk begin voor een klein team, en 14 dagen is voldoende als u alleen een trace opent wanneer er iets misgaat.
Het tweede zijn de eigen systeemlogtabellen van ClickHouse. Dit verrast mensen vaak, omdat de schijf blijft groeien nadat de retentie is geconfigureerd. ClickHouse schrijft trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log en latency_log voor zijn eigen diagnostiek. Deze worden zonder TTL geleverd en Langfuse leest ze nooit. Achterhaal eerst waar de schijfruimte daadwerkelijk naartoe gaat.
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
)Voer dit uit met docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Als systeemtabellen bovenaan staan, schakel ze dan uit met een configuratie-overlay, omdat ClickHouse bij het opstarten elk bestand in /etc/clickhouse-server/config.d/ over zijn hoofdconfiguratie heen samenvoegt.
<clickhouse>
<trace_log remove="1"/>
<text_log remove="1"/>
<opentelemetry_span_log remove="1"/>
<asynchronous_metric_log remove="1"/>
<metric_log remove="1"/>
<latency_log remove="1"/>
</clickhouse>Mount dit en herstart ClickHouse.
services:
clickhouse:
volumes:
- ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:roDit stopt nieuwe schrijfacties. Rijen die al op de schijf staan, blijven daar staan, dus claim de ruimte expliciet terug met DROP TABLE IF EXISTS system.trace_log en doe hetzelfde voor elke tabel die u heeft verwijderd. Als u de diagnostiek liever behoudt, is het alternatief een agressieve TTL op elke tabel in plaats van remove="1", zoals beschreven in de schaalbaarheidsdocumentatie van Langfuse. Deze TTL-richtlijnen zijn alleen van toepassing wanneer een systeemtabel voor het eerst wordt aangemaakt; bij een bestaande installatie leggen dezelfde documenten uit hoe u de tabellen achteraf kunt aanpassen.
Er is nog één tabel die het vermelden waard is. blob_storage_file_log houdt de event-bestanden bij die naar uw bucket zijn geüpload. Als u ook een lifecycle-beleid op de bucket instelt, geef de tabel dan een overeenkomstige TTL zodat de twee niet uit de pas gaan lopen.
ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;Stel ook een eenvoudige df -h-waarschuwing in op de gegevensschijf. Traces groeien niet gelijkmatig. Ze groeien op de dag dat u een nieuwe agent uitrolt, en het eerste teken daarvan mag niet zijn dat de gegevensopname faalt.
Back-up van Postgres en ClickHouse
Een Langfuse-back-up bestaat uit drie onderdelen. Postgres bevat uw gebruikers, organisaties, projecten en API-keys. ClickHouse bevat de traces. MinIO bevat de ruwe events. Als u alleen Postgres herstelt, beschikt u over een werkende login zonder historie. Als u alleen ClickHouse herstelt, beschikt u over historie die niemand kan inzien. Deze splitsing is niet uniek voor Langfuse; een zelfgehoste Chatwoot-supportdesk heeft dezelfde structuur, waarbij een Postgres-dump zonder de uploads-map resulteert in conversaties waarvan alle bijlagen verdwenen zijn.
Postgres is een eenvoudige pg_dump, wat de methode is die de Langfuse-documentatie voor een Docker-installatie adviseert.
docker compose exec -T postgres pg_dump -U postgres postgres \
| gzip > langfuse-pg-$(date +%F).sql.gzClickHouse vereist meer zorgvuldigheid, omdat een live datamap die wordt gekopieerd terwijl er merges plaatsvinden, geen consistente back-up oplevert. De eenvoudige aanpak op één server is het stoppen van de container en het archiveren van het 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 clickhouseGebruik de volumenaam die docker volume ls weergeeft, niet de naam die in de YAML staat. Het bestand declareert langfuse_clickhouse_data, en Compose voegt daar het projectnaam-voorvoegsel aan toe. Een kloon in een map genaamd langfuse resulteert dus in langfuse_langfuse_clickhouse_data. Als u dit fout doet, maakt docker run een nieuw leeg volume aan zonder foutmelding, en bevat uw archief niets.
Langfuse uploadt ruwe eventdata bij elk ingestieverzoek naar de bucket en leest deze opnieuw in om mislukte ingestietaken opnieuw uit te voeren. Een korte stop van ClickHouse betekent dus meestal dat de worker het daarna opnieuw probeert. Voer dit uit tijdens een rustig moment en houd de duur kort. Voor een drukkere instantie schrijft het eigen BACKUP DATABASE default TO S3(...)-statement van ClickHouse een consistente back-up zonder de server te stoppen. MinIO is het derde onderdeel, en mc mirror of MinIO-replicatie naar een externe bucket dekt dit af. Wat u ook produceert, haal het van de server af; daarvoor zijn versleutelde restic-back-ups op een VPS bedoeld.
Redis bevat de wachtrij en de cache. Verlies hiervan betekent dat taken in de wachtrij verloren gaan, zelfs als hun ruwe eventbestanden in de bucket blijven staan.
Het voorbehoud wat betreft consistentie is reëel en moet duidelijk worden benoemd. Postgres en ClickHouse worden op verschillende momenten gedumpt, waardoor een herstel kan leiden tot een projectrij zonder traces, of traces die behoren bij een project dat niet meer bestaat. Langfuse tolereert dit, maar maak beide dumps kort na elkaar en tijdens een venster met weinig verkeer. De event-bucket is het echte vangnet, omdat Langfuse daar bij elk ingestieverzoek ruwe eventdata naartoe uploadt.
Herstel ten minste één keer naar een testomgeving. Zo ontdekt u nu een verkeerde volumenaam, in plaats van tijdens een storing.
Waar u als eerste naar moet kijken
Vier zaken verdienen in de eerste week uw aandacht.
- Kosten per trace. Langfuse berekent de kosten op basis van de modelnaam en het tokenverbruik. Sorteer traces daarom op kosten en bekijk de duurste trace van begin tot eind. Het antwoord is meestal een prompt die te groot is geworden: een volledig document dat in de context is geplakt, of een gespreksgeschiedenis die niet wordt ingekort. Zodra u dit inzicht heeft, wordt het beheersen van de kosten van een AI-agent een technische taak in plaats van giswerk.
- Verdeling van tokenverbruik tussen input en output. Input-tokens zijn talrijk en goedkoop, output-tokens zijn schaars en duur, en gecachte input is nog goedkoper. Dezelfde berekening wordt uitgelegd in hoe het tokenverbruik van Claude Code wordt geteld, en dit is van toepassing op elke agent die u zelf schrijft.
- Latentie-percentielen. De mediaan verbergt het probleem. Bij p95 en p99 bevinden zich de timeouts. Binnen een agent-loop wordt een trage tool-aanroep bij p95 vermenigvuldigd met het aantal iteraties.
- Mislukte tool-aanroepen. Filter observaties op niveau
ERROR. Een tool die in 5% van de gevallen faalt, is onzichtbaar in een geaggregeerd succespercentage, maar zeer zichtbaar in de traces. Hier ziet u hoe het model het opnieuw probeert en vervolgens tokens verbruikt om het probleem te omzeilen.
Stel de retentieperiode in en kies het dashboard dat u wekelijks op dezelfde dag als uw deployment controleert. Een observability-tool die niemand opent, is slechts een database die een schijf vult.
FAQ
Hoeveel geheugen heeft een zelfgehoste Langfuse nodig?
Houd rekening met 4 CPU-cores en 16 GiB geheugen; dit is wat de Docker Compose-handleiding van Langfuse aanbeveelt voor een enkele virtuele machine, plus ongeveer 100 GiB opslagruimte. De gepubliceerde minimumvereisten voor componenten zijn 8 GiB voor ClickHouse en 4 GiB per stuk voor de web- en worker-containers. Dezelfde pagina vermeldt 4 GiB voor Postgres, 1.5 GiB voor Redis en 4 GiB voor MinIO, waardoor het totaal voor alle zes op 25.5 GiB uitkomt, wat meer is dan de aanbeveling van 16 GiB voor Compose.
Waarom loopt mijn ClickHouse-schijf vol nadat ik dataretentie heb ingesteld?
De retentie-instelling heeft alleen betrekking op de eigen gegevens van Langfuse. ClickHouse schrijft afzonderlijk zijn diagnostische tabellen trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log en latency_log, en deze worden geleverd zonder TTL. Voer query system.parts uit, gegroepeerd per tabel, om te zien welke het grootst is. Schakel vervolgens de ongebruikte tabellen uit met een remove="1"-vermelding in een bestand onder /etc/clickhouse-server/config.d/, start ClickHouse opnieuw op en verwijder de bestaande tabellen om de reeds gebruikte ruimte vrij te maken.
Wat is de minimale dataretentieperiode in Langfuse?
Drie dagen. Retentie wordt per project ingesteld in de projectinstellingen, of via de Organization Management API. Een nachtelijke taak verwijdert traces, observaties, scores en media-assets die ouder zijn dan het venster uit zowel ClickHouse als de blob-opslag, met uitzondering van media die gekoppeld zijn aan opgeslagen dataset-items. Op een zelfgehoste instantie is dit een Enterprise Edition-functie waarvoor een licentiesleutel vereist is. Zonder licentiesleutel worden gegevens voor onbepaalde tijd bewaard. Verwijdering kan niet ongedaan worden gemaakt; configureer daarom eerst een export naar blob-opslag als u de historie na dat venster wilt behouden.
Moet ik zowel Postgres als ClickHouse back-uppen?
Ja, omdat ze verschillende gegevens bevatten. Postgres bevat gebruikers, organisaties, projecten en API-sleutels, terwijl ClickHouse de trace-gegevens zelf bevat. Een herstel van alleen Postgres levert een instantie op waar u op kunt inloggen, maar die leeg is. Maak ook een back-up van de MinIO-bucket, aangezien deze de ruwe events bevat die Langfuse bij aankomst opslaat; dit is de meest betrouwbare bron van waarheid in de stack.
Kan ik een bestaande OpenTelemetry-configuratie naar een zelfgehoste Langfuse laten wijzen?
Ja. Langfuse v4 en de huidige SDK's zijn gebouwd op OpenTelemetry, en de OTel-instrumentaties voor Anthropic en OpenAI exporteren hier direct naartoe. Voer in Python pip install langfuse opentelemetry-instrumentation-anthropic uit, roep AnthropicInstrumentor().instrument() eenmalig aan bij het opstarten en stel LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY en LANGFUSE_BASE_URL in op uw eigen host. Bevestig dit met langfuse.auth_check() voordat u op zoek gaat naar een ontbrekend dashboard.