Samodzielny hosting Langfuse na własnym VPS
Instrukcja wdrożenia Langfuse na własnym serwerze. Optymalizacja ClickHouse, konfiguracja TLS, przypinanie wersji obrazów Docker oraz strategia backupu danych dla AI.
Dlaczego warto śledzić działanie agenta AI
Samodzielne hostowanie Langfuse pozwala sprawdzić, co faktycznie wykonał agent podczas uruchomienia. Langfuse to narzędzie open source do monitorowania LLM (large language model). Rejestruje ono każdy prompt, każdą odpowiedź modelu, każde wywołanie narzędzia oraz każdy token, a następnie grupuje je w ramach jednego śledzenia (trace), które można otworzyć i przeanalizować. Uruchomienie narzędzia na własnym VPS gwarantuje, że prompty nigdy nie opuszczają serwera, nad którym sprawujesz kontrolę.
Powód, dla którego warto to robić, jest oczywisty. Nie można naprawić problemów z kosztami ani jakością, których nie można zaobserwować. Faktura od dostawcy informuje, że wtorek kosztował cztery razy więcej niż poniedziałek. Śledzenie wskazuje, które uruchomienie agenta było przyczyną, który prompt urósł do 40,000 tokenów oraz która pętla ponownych prób wykonała się dziewięć razy przed przerwaniem działania. Faktura podaje liczbę. Śledzenie wskazuje kod, który ją wygenerował.
W niniejszym przewodniku użyto trzech terminów. Trace (śledzenie) to jedno pełne uruchomienie agenta od początku do końca. Observation (obserwacja) to pojedynczy krok wewnątrz tego uruchomienia: span dla zwykłego kodu lub generation dla wywołania modelu. Score (wynik) to liczba przypisana do śledzenia, pochodząca z oceny ludzkiej lub automatycznego ewaluatora. Langfuse obsługuje OpenTelemetry (OTel), czyli niezależny od dostawcy standard śledzenia rozproszonego, dzięki czemu istniejąca już instrumentacja może być skierowana na to narzędzie.
Co faktycznie uruchamia samodzielnie hostowany Langfuse
Langfuse w wersji v4 nie jest pojedynczym kontenerem. To dwa kontenery aplikacji oraz cztery usługi pamięci masowej, a na pojedynczym serwerze VPS wszystkie sześć działa na jednej maszynie.
langfuse-webobsługuje interfejs WWW oraz API przyjmowania danych.langfuse-workeropróżnia kolejkę w tle. Analizuje partie danych, oblicza koszty i uruchamia nocne zadanie retencji.- Postgres przechowuje dane transakcyjne, takie jak użytkownicy, organizacje, projekty, klucze API oraz prompty.
- ClickHouse przechowuje same dane śledzenia (trace), czyli obserwacje i wyniki. Jest to kolumnowa baza danych stworzona do zapytań analitycznych, dzięki czemu dashboardy działające na stu milionach wierszy odpowiadają szybko.
- Redis pełni rolę kolejki i pamięci podręcznej między interfejsem WWW a procesem roboczym (worker).
- MinIO zapewnia zgodną z S3 pamięć obiektową na serwerze. Przechowuje każde surowe przychodzące zdarzenie oraz wszelkie dołączone media.
Langfuse publikuje minimalne wymagania zasobowe dla każdego uruchamianego komponentu. Poniższy wykres przedstawia trzy z nich, które wykonują główną pracę.
Dane, na których opiera się ten wykres
[
{
"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
}
]Sam ClickHouse wymaga 8 GiB pamięci RAM. Kontener WWW oraz proces roboczy wymagają po 4 GiB każdy. Są to opublikowane wartości minimalne dla 3 komponentów na wykresie. Ta sama strona wymienia Postgres z 4 GiB, Redis lub Valkey z 1.5 GiB oraz MinIO z 4 GiB, więc suma minimów dla wszystkich sześciu wynosi 25.5 GiB. Dokumentacja projektu dotycząca Docker Compose zaleca co najmniej 4 rdzenie, 16 GiB pamięci RAM i około 100 GiB przestrzeni dyskowej dla pojedynczej maszyny. Jest to wartość mniejsza niż suma minimów komponentów, więc 16 GiB należy traktować jako absolutne minimum dla współdzielonej instancji Compose, a nie jako zapas mocy.
Nie należy podejmować prób uruchomienia na planie z 2 GiB pamięci. ClickHouse uruchomi się, przez pewien czas będzie przyjmował zapisy, a następnie ulegnie awarii podczas scalania danych w tle, ponieważ proces ten ładuje duże fragmenty tabeli do pamięci. W takiej sytuacji docker compose ps zgłosi kontener clickhouse jako restarting, dmesg wyświetli komunikat w stylu Out of memory: Killed process 1234 (clickhouse-serv), a każdy dashboard Langfuse zwróci błąd 500. Przy mniejszym obciążeniu ClickHouse odrzuci zapytanie i zapisze w logach DB::Exception: Memory limit (total) exceeded. 16 to liczba, którą należy przyjąć w planowaniu. Jeśli ten sam serwer VPS ma obsługiwać cokolwiek innego, należy zarezerwować na to osobne zasoby, ponieważ nawet stosunkowo lekki zestaw, taki jak samodzielnie hostowany obszar roboczy AFFiNE, wymaga własnych gigabajtów, a ClickHouse nie zwolni przydzielonej pamięci.
Wdrożenie Langfuse przy użyciu Docker Compose
Sklonuj repozytorium. Stos, powiązania oraz domyślne środowisko znajdują się w jego docker-compose.yml.
git clone https://github.com/langfuse/langfuse.git
cd langfuseKażda wartość wymagająca zmiany jest oznaczona w tym pliku jako # CHANGEME. Najpierw wygeneruj trzy sekrety aplikacji.
openssl rand -base64 32 # NEXTAUTH_SECRET
openssl rand -base64 32 # SALT
openssl rand -hex 32 # ENCRYPTION_KEYWartość ENCRYPTION_KEY musi mieć 256 bitów zapisanych jako 64 znaki szesnastkowe, co dokładnie generuje polecenie openssl rand -hex 32. Służy ona do szyfrowania wrażliwych danych w spoczynku, w tym kluczy dostawców LLM przechowywanych w instancji. Zmiana tej wartości po zapisaniu danych uniemożliwi ich odszyfrowanie, dlatego należy ją traktować jako stałą od pierwszego uruchomienia. Wartość SALT jest używana do haszowania kluczy API Langfuse, więc jej zmiana unieważni wszystkie klucze używane obecnie przez agentów.
Następnie ustaw POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH oraz MINIO_ROOT_PASSWORD. Hasło MinIO występuje w czterech miejscach: raz jako MINIO_ROOT_PASSWORD, a następnie jako LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY oraz LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Pominięcie jednego z nich spowoduje, że MinIO odrzuci klienta z błędem SignatureDoesNotMatch, który pojawi się w dzienniku procesu worker, podczas gdy interfejs WWW będzie wyglądał na działający poprawnie. Przechowywanie tych wartości w pliku env zamiast w śledzonym pliku compose to wzorzec opisany w plikach env i sekretach Docker Compose.
Przypięcie tagów obrazów przed uruchomieniem
Dostarczony plik używa docker.langfuse.com/langfuse/langfuse:4 oraz docker.langfuse.com/langfuse/langfuse-worker:4. Te tagi są zmienne. Langfuse automatycznie wykonuje migracje Postgres i ClickHouse przy starcie, więc rutynowe polecenie docker compose pull wykonane kilka miesięcy później może stać się nieplanowaną migracją schematu bazy danych, której nie wykonano kopii zapasowej tego samego dnia. Przypnij oba obrazy do konkretnej wersji w pliku docker-compose.override.yml, który Compose scala z dostarczonym plikiem, dzięki czemu późniejsze polecenie git pull nie nadpisze Twoich zmian. Te same obrazy są publikowane w Docker Hub, skąd pobiera je poniższe nadpisanie.
services:
langfuse-web:
image: docker.io/langfuse/langfuse:4.72.0
langfuse-worker:
image: docker.io/langfuse/langfuse-worker:4.72.0Wersja 4.3.1 była aktualnym wydaniem 4.3 w sierpniu 2026 roku. Od tego czasu wydania pojawiały się szybko, a v4.56.0 była najnowszą wersją na GitHubie w dniu 11 października 2026 roku. Powyższe nadpisanie używa v4.72.0, najnowszej wersji na GitHubie w dniu 31 października 2026 roku. Sprawdź stronę wydań projektu na GitHubie, przypnij wersję aktualną w dniu wdrożenia, a następnie zmieniaj ten numer w sposób świadomy. Niektóre obrazy pamięci masowej w dostarczonym pliku wymagają takiego samego traktowania, ponieważ ich tagi również ulegają zmianie. postgres:17 (wartość domyślna zmiennej POSTGRES_VERSION) oraz redis:7 podążają za główną wersją. Dostarczony plik używa teraz dokładnego tagu wersji dla docker.io/clickhouse/clickhouse-server, przypinając konkretną wersję ClickHouse. Ta zasada nie dotyczy tylko Langfuse: samodzielnie hostowany tracker treningów openGym uruchamia ułamek tego stosu i nadal wymaga nazwanego tagu git, ponieważ wszystko, co migruje własną bazę danych przy starcie, może zmienić rutynowe pobranie w zmianę schematu.
Uruchom stos.
docker compose up -d
docker compose ps
docker compose logs -f langfuse-workerPierwsze uruchomienie wykonuje migracje, więc odczekaj dwie lub trzy minuty, zanim usługa zacznie odpowiadać. Kontener WWW zapisuje w dzienniku Ready, gdy jest gotowy. Polecenie docker compose ps powinno wyświetlić sześć usług w stanie running. Jeśli kontener restartuje się w pętli, jego dziennik zawiera przyczynę. Migracje ClickHouse są stosowane, gdy uruchamia się kontener WWW, więc błąd CLICKHOUSE_MIGRATION_URL pojawi się w docker compose logs langfuse-web, a nie w dzienniku procesu worker, który monitorujesz. Ta zmienna używa natywnego protokołu ClickHouse na porcie 9000, a nie portu HTTP 8123; wskazanie portu 8123 przerywa migracje startowe kontenera WWW. Proces worker wykonuje wolniejsze migracje w tle, więc to w jego dzienniku pojawiają się raporty z tych operacji.
Sprawdź stan usługi z poziomu serwera.
curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/readyZwykłe wywołanie /api/public/health potwierdza jedynie, że proces API działa, ponieważ domyślnie nie sprawdza on bazy danych. Formularz failIfDatabaseUnavailable=true jest tym, który warto monitorować; zwraca on 503, gdy baza danych jest nieosiągalna. /api/public/ready zwraca 200, gdy kontener WWW jest gotowy do przyjmowania ruchu, oraz 500, gdy otrzymał polecenie zamknięcia. Oba są standardowymi sprawdzeniami HTTP, więc strona statusu Uptime Kuma może je monitorować i powiadomić o awarii stosu, zanim zrobią to agenci.
Umieszczenie TLS przed aplikacją i zamknięcie dodatkowych portów
Dostarczony plik compose publikuje 3000:3000 dla kontenera web oraz 9090:9000 dla MinIO. Oba wiążą się z każdym interfejsem sieciowym. Na publicznym adresie IP oznacza to, że każdy, kto przeskanuje port 3000, uzyska dostęp do strony rejestracji, a każdy, kto przeskanuje 9090, połączy się z zasobnikiem przechowującym surowe prompty.
Sama reguła firewalla nie wystarczy, aby je zamknąć. Docker zapisuje własne reguły DNAT w tablicy nat, które są przetwarzane, zanim reguły filtrujące ufw zobaczą pakiet, więc ufw deny 3000 pozostawia opublikowany port otwartym. Problem ten dotyczy wystarczającej liczby użytkowników, aby posiadać własny przewodnik: dlaczego opublikowane porty Dockera omijają ufw. Zamiast tego należy powiązać porty z interfejsem loopback w pliku override. Użyj !override w Docker Compose 2.24.4 lub nowszym, aby zastąpić opublikowane porty; zwykła lista łączy się z oryginalnymi powiązaniami.
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 musi być dokładnym adresem publicznym wraz ze schematem, ponieważ proces logowania buduje adres URL wywołania zwrotnego (callback URL) na podstawie tej wartości. Pozostawienie http://localhost:3000 za proxy HTTPS spowoduje, że cykl logowania przekieruje przeglądarkę w miejsce, do którego nie ma dostępu.
Teraz skieruj reverse proxy na 127.0.0.1:3000 i pozwól mu zarządzać certyfikatem. W przypadku Traefik w tym samym projekcie Compose, kieruj ruch na langfuse-web:3000 przez sieć Compose, używając etykiet opisanych w uruchamianie kilku aplikacji za jednym reverse proxy Traefik. Caddy wykonuje to samo zadanie w dwóch liniach, jeśli Langfuse jest jedyną usługą na serwerze. Zweryfikuj konfigurację za pomocą curl -sI https://langfuse.example.com/api/public/ready, a następnie potwierdź z drugiego urządzenia, że curl http://YOUR_IP:3000 nie może nawiązać połączenia.
Jedno zastrzeżenie dotyczące MinIO. Langfuse przekazuje wstępnie podpisane adresy URL (presigned URLs) wskazujące na ten punkt końcowy S3, zarówno do SDK przesyłających multimedia, jak i do przeglądarki ładującej te dane. Jeśli używasz śladów multimodalnych zawierających obrazy lub dźwięk, MinIO ograniczone do loopback spowoduje, że załączniki nie będą przesyłane z innych maszyn ani ładowane w przeglądarce. Przed skonfigurowaniem proxy przeczytaj stronę konfiguracji pamięci obiektowej (blob storage), ponieważ punkt końcowy zapisany w presigned URL, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, musi być zgodny z tym, co publikujesz. Ślady w formacie tekstowym pozostają bez zmian.
Utwórz konto przy pierwszej wizycie, a następnie zabezpiecz instancję. Ustaw AUTH_DISABLE_SIGNUP=true po utworzeniu konta, aby osoba postronna, która trafi na stronę, nie mogła się zarejestrować. Langfuse posiada również LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, co ogranicza możliwość tworzenia organizacji, jednak jest to funkcja Enterprise Edition i wymaga klucza licencyjnego. Jeśli korzystasz już z Authentik jako własnego dostawcy tożsamości, Langfuse obsługuje standardowe połączenie OIDC, dzięki czemu konta są zarządzane centralnie wraz z pozostałymi aplikacjami, zamiast znajdować się na liście haseł znanej tylko tej maszynie.
Wysłanie pierwszego śladu (trace)
Utwórz projekt w interfejsie WWW i skopiuj klucze publiczne oraz tajne z ustawień projektu. Python SDK odczytuje trzy zmienne środowiskowe.
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"LANGFUSE_BASE_URL to nazwa zmiennej w SDK v4, wydanym w marcu 2026 roku. Starszy kod i starsze poradniki używają LANGFUSE_HOST. Jeśli ślady trafiają do Langfuse Cloud zamiast na własny serwer, przyczyną jest nieustawiony bazowy adres URL, ponieważ wartość domyślna wskazuje na instancję hostowaną.
Obecny Python SDK v5 wymaga języka Python w wersji 3.11 lub nowszej oraz samodzielnie hostowanego Langfuse w wersji 4.59.0 lub nowszej, co spełnia powyższa konfiguracja serwera.
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()Dekorator @observe otwiera obserwację wokół funkcji, przechwytuje jej argumenty oraz wartość zwracaną i zagnieżdża ją pod dowolną już aktywną obserwacją. AnthropicInstrumentor to instrumentacja OpenTelemetry dla klienta Anthropic, która zamienia każde wywołanie messages.create w generację zawierającą nazwę modelu, zużycie tokenów oraz opóźnienie, bez konieczności wprowadzania zmian w miejscu wywołania.
Dwa wywołania pozwalają na weryfikację poprawności. langfuse.auth_check() zwraca False w przypadku błędnych kluczy lub nieprawidłowego bazowego adresu URL, co pozwala uniknąć sprawdzania, dlaczego dashboard jest pusty. langfuse.flush() blokuje działanie do momentu wysłania zakolejkowanych zakresów (spans), co jest niezbędne w procesach o krótkim czasie życia, ponieważ SDK wykonuje operacje wsadowe w tle, a skrypt kończący działanie natychmiast zabiera ze sobą niewysłaną partię danych. Jeśli ślady wysyła cały zespół, a nie pojedynczy skrypt, należy ustawić te trzy zmienne raz w bramce, przez którą przechodzą agenci wszystkich użytkowników, zamiast w powłoce każdej osoby. W ten sposób samodzielnie hostowany zestaw narzędzi OneCLI utrzymuje instrumentację uruchomień wszystkich współpracowników, podczas gdy klucze pozostają w jednym miejscu.
Dlaczego ClickHouse stale zwiększa zajętość dysku?
Ślady (traces) to najszybciej rosnący typ danych w większości samodzielnie hostowanych instancji. Każde uruchomienie agenta generuje jeden wiersz na krok, a dane wejściowe i wyjściowe są zapisywane w całości. W rezultacie "rozgadany" agent z długimi promptami generuje znacznie więcej bajtów dziennie niż monitorowana przez niego aplikacja. Pozostawiony bez nadzoru ClickHouse zapełnia dysk, a pełny dysk powoduje zatrzymanie przyjmowania danych (ingestion), zamiast jedynie spowolnić ten proces.
Wzrost ten wynika z dwóch niezależnych przyczyn, które wymagają osobnych rozwiązań.
Pierwszą z nich są własne dane śladów, a rozwiązaniem jest ustawienie retencji. W instancji self-hosted retencja danych jest funkcją wersji Enterprise i wymaga klucza licencyjnego. Bez niego Langfuse przechowuje ślady, obserwacje, wyniki i multimedia bezterminowo. Należy zatem odpowiednio zaplanować rozmiar dysku i polegać na alertach dotyczących zajętości miejsca, opisanych na końcu tej sekcji. Po aktywacji licencji właściciele projektów i administratorzy mogą w ustawieniach projektu zdefiniować okres retencji danych w dniach. Langfuse wymaga ustawienia minimum 3 dni. Zadanie uruchamiane w nocy wyszukuje ślady, obserwacje, wyniki i zasoby multimedialne starsze niż wskazany okres i usuwa je z ClickHouse oraz z pamięci obiektowej (blob storage), z wyjątkiem multimediów powiązanych z zapisanymi elementami zbiorów danych (datasets). Zadanie to wymaga uprawnień DeleteObject do zasobnika (bucket), które poświadczenia root MinIO w domyślnym pliku compose już posiadają. Usunięcie jest trwałe, więc jeśli wymagana jest długoterminowa historia, należy najpierw skonfigurować eksport do pamięci obiektowej. Nie należy ręcznie dodawać klauzul TTL do tabel Langfuse: zadanie retencji zapewnia spójność między ClickHouse a zasobnikiem, natomiast ręczne ustawienie TTL usunie dane tylko z jednej strony.
Okres retencji należy dobrać do faktycznych potrzeb. Przegląd kosztów i jakości odbywa się na danych sprzed kilku dni, a nie miesięcy. 30 dni to rozsądny punkt wyjścia dla małego zespołu, a 14 dni wystarczy, jeśli ślady otwiera się tylko w przypadku awarii.
Drugą przyczyną są systemowe tabele logów ClickHouse. Jest to zaskakujące dla wielu użytkowników, ponieważ dysk nadal się zapełnia nawet po skonfigurowaniu retencji danych użytkownika. ClickHouse zapisuje trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log oraz latency_log na potrzeby własnej diagnostyki. Tabele te nie mają domyślnego TTL, a Langfuse nigdy ich nie odczytuje. Najpierw należy sprawdzić, co faktycznie zajmuje miejsce na dysku.
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
)Uruchom powyższe polecenie z flagą docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Jeśli tabele systemowe znajdują się na szczycie listy, należy je wyłączyć za pomocą nakładki konfiguracyjnej, ponieważ ClickHouse przy starcie scala każdy plik z /etc/clickhouse-server/config.d/ ze swoją główną konfiguracją.
<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>Zamontuj plik i zrestartuj ClickHouse.
services:
clickhouse:
volumes:
- ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:roTo zatrzyma nowe zapisy. Wiersze już znajdujące się na dysku pozostaną, więc należy odzyskać miejsce jawnie za pomocą DROP TABLE IF EXISTS system.trace_log dla każdej usuniętej tabeli. Jeśli diagnostyka jest wymagana, alternatywą jest ustawienie agresywnego TTL dla każdej tabeli zamiast remove="1", co opisano w dokumentacji skalowania Langfuse. Dyrektywy TTL mają zastosowanie tylko w momencie tworzenia tabeli systemowej, więc w przypadku istniejącej instalacji wspomniana dokumentacja zawiera również instrukcję modyfikacji istniejących tabel.
Warto również zwrócić uwagę na jeszcze jedną tabelę. blob_storage_file_log śledzi pliki zdarzeń przesłane do zasobnika. Jeśli dla zasobnika ustawiono politykę cyklu życia (lifecycle policy), należy nadać tej tabeli pasujący TTL, aby oba mechanizmy pozostały zsynchronizowane.
ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;Należy również ustawić prosty alert df -h na dysku z danymi. Ślady nie przyrastają w sposób liniowy. Ich ilość gwałtownie rośnie w dniu wdrożenia nowego agenta, a awaria przyjmowania danych nie powinna być pierwszym sygnałem tego zdarzenia.
Tworzenie kopii zapasowych Postgres i ClickHouse
Kopia zapasowa Langfuse składa się z trzech części. Postgres przechowuje użytkowników, organizacje, projekty oraz klucze API. ClickHouse przechowuje ślady (traces). MinIO przechowuje surowe zdarzenia. Przywrócenie tylko Postgresa pozwala na logowanie, ale bez historii. Przywrócenie tylko ClickHouse daje dostęp do historii, do której nikt nie może się zalogować. Ten podział nie jest unikalny dla Langfuse; własna instancja Chatwoot ma taką samą strukturę, gdzie zrzut Postgresa wykonany bez katalogu z plikami przesyłanymi przez użytkowników powoduje przywrócenie konwersacji, w których brakuje wszystkich załączników.
Postgres to zwykły pg_dump, co jest metodą zalecaną w dokumentacji Langfuse dla instalacji Docker.
docker compose exec -T postgres pg_dump -U postgres postgres \
| gzip > langfuse-pg-$(date +%F).sql.gzClickHouse wymaga większej uwagi, ponieważ katalog danych skopiowany w trakcie trwania procesów scalania (merges) nie stanowi spójnej kopii zapasowej. Najprostszym podejściem na pojedynczej maszynie jest zatrzymanie kontenera i zarchiwizowanie wolumenu.
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 clickhouseNależy użyć nazwy wolumenu wyświetlanej przez docker volume ls, a nie tej zapisanej w pliku YAML. Plik deklaruje langfuse_clickhouse_data, a Compose dodaje prefiks z nazwą projektu, więc klon w katalogu o nazwie langfuse tworzy langfuse_langfuse_clickhouse_data. Błąd w tym miejscu sprawi, że docker run utworzy nowy, pusty wolumen bez zgłaszania ostrzeżeń, a archiwum będzie puste.
Langfuse przesyła surowe dane zdarzeń do bucketa przy każdym żądaniu przyjęcia danych i odczytuje je ponownie w celu ponowienia nieudanych zadań, więc krótkie zatrzymanie ClickHouse zazwyczaj kończy się ponowieniem operacji przez worker. Czynność tę należy wykonać w godzinach o niskim ruchu i przeprowadzić ją szybko. W przypadku bardziej obciążonej instancji, polecenie BACKUP DATABASE default TO S3(...) wbudowane w ClickHouse pozwala na wykonanie spójnej kopii zapasowej bez zatrzymywania serwera. MinIO stanowi trzeci element, a mc mirror lub replikacja MinIO do zewnętrznego bucketa zapewnia jego ochronę. Niezależnie od metody, kopię należy przenieść poza serwer, do czego służą szyfrowane kopie zapasowe restic na VPS.
Redis przechowuje kolejkę i pamięć podręczną. Utrata tych danych powoduje odrzucenie zadań w kolejce, nawet jeśli pliki surowych zdarzeń pozostają w buckecie.
Zastrzeżenie dotyczące spójności jest istotne i należy je wyraźnie podkreślić. Postgres i ClickHouse są zrzucane w różnych momentach, więc przywrócenie może pozostawić wiersz projektu bez powiązanych śladów lub ślady należące do projektu, który już nie istnieje. Langfuse toleruje takie sytuacje, jednak zrzuty należy wykonywać w krótkim odstępie czasu i w oknie o niskim natężeniu ruchu. Bucket ze zdarzeniami stanowi rzeczywistą siatkę bezpieczeństwa, ponieważ Langfuse przesyła tam surowe dane zdarzeń przy każdym żądaniu.
Należy przynajmniej raz przeprowadzić przywracanie na środowisku testowym. Pozwala to wykryć błędną nazwę wolumenu teraz, a nie w trakcie rzeczywistej awarii.
Na co zwrócić uwagę w pierwszej kolejności
Cztery elementy zasługują na uwagę w pierwszym tygodniu.
- Koszt pojedynczego śladu (trace). Langfuse oblicza koszt na podstawie nazwy modelu i zużycia tokenów, dlatego warto posortować ślady według kosztu i przeanalizować najbardziej kosztowny od początku do końca. Przyczyną jest zazwyczaj rozrośnięty prompt: cały dokument wklejony do kontekstu lub historia konwersacji, która nie jest przycinana. Gdy już to widać, kontrolowanie kosztów agenta AI staje się zadaniem inżynieryjnym, a nie zgadywaniem.
- Podział zużycia tokenów na wejściowe i wyjściowe. Tokeny wejściowe są liczne i tanie, wyjściowe są nieliczne i drogie, a buforowane dane wejściowe są jeszcze tańsze. Ten sam sposób rozliczania został wyjaśniony w sposobie zliczania tokenów w Claude Code i ma zastosowanie do każdego agenta stworzonego samodzielnie.
- Percentyle opóźnień. Mediana ukrywa problem. Wartości p95 i p99 to miejsca, w których występują przekroczenia limitów czasu (timeouts), a w pętli agenta wolne wywołanie narzędzia przy p95 jest mnożone przez liczbę iteracji.
- Nieudane wywołania narzędzi. Przefiltruj obserwacje według poziomu
ERROR. Narzędzie, które zawodzi w 5% przypadków, jest niewidoczne w zagregowanym wskaźniku sukcesu, ale bardzo widoczne w śladach, gdzie można zaobserwować, jak model ponawia próbę, a następnie zużywa tokeny na obejście problemu.
Ustaw okres retencji i wybierz pulpit nawigacyjny, który będziesz sprawdzać co tydzień, w tym samym dniu, w którym wdrażasz zmiany. Narzędzie do obserwowalności, którego nikt nie otwiera, to tylko baza danych zapełniająca dysk.
FAQ
Ile pamięci RAM wymaga samodzielnie hostowany Langfuse?
Należy zaplanować 4 rdzenie CPU oraz 16 GiB pamięci RAM, co jest wartością zalecaną w przewodniku Docker Compose dla Langfuse w przypadku pojedynczej maszyny wirtualnej, oraz około 100 GiB miejsca na dysku. Opublikowane minimalne wymagania dla komponentów to 8 GiB dla ClickHouse oraz 4 GiB odpowiednio dla kontenerów web i worker. Ta sama strona wskazuje 4 GiB dla Postgres, 1.5 GiB dla Redis oraz 4 GiB dla MinIO, co łącznie daje 25.5 GiB, czyli więcej niż 16 GiB zalecane w konfiguracji Compose.
Dlaczego dysk ClickHouse zapełnia się mimo ustawienia retencji danych?
Ustawienie retencji obejmuje wyłącznie dane własne Langfuse. ClickHouse zapisuje oddzielnie tabele diagnostyczne trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log oraz latency_log, które nie posiadają domyślnego TTL. Należy wykonać zapytanie system.parts pogrupowane według tabeli, aby zidentyfikować największą z nich, a następnie wyłączyć nieużywane tabele za pomocą wpisu remove="1" w pliku w lokalizacji /etc/clickhouse-server/config.d/, zrestartować ClickHouse i usunąć istniejące tabele w celu odzyskania zajętego miejsca.
Jaki jest minimalny okres retencji danych w Langfuse?
Trzy dni. Retencję ustawia się dla każdego projektu w ustawieniach projektu lub poprzez Organization Management API. Zadanie uruchamiane w nocy usuwa ślady (traces), obserwacje, wyniki (scores) oraz zasoby multimedialne starsze niż wyznaczony okres, zarówno z ClickHouse, jak i z pamięci obiektowej (blob storage), z wyjątkiem multimediów powiązanych z zapisanymi elementami zbiorów danych (dataset items). W instancji hostowanej samodzielnie jest to funkcja Enterprise Edition wymagająca klucza licencyjnego. Bez licencji dane są przechowywane bezterminowo. Usunięcia nie można cofnąć, dlatego przed ustawieniem retencji należy skonfigurować eksport do pamięci obiektowej, jeśli wymagane jest zachowanie historii wykraczającej poza ten okres.
Czy muszę tworzyć kopie zapasowe zarówno Postgres, jak i ClickHouse?
Tak, ponieważ przechowują one różne dane. Postgres przechowuje użytkowników, organizacje, projekty oraz klucze API, natomiast ClickHouse przechowuje same dane śledzenia (trace data). Przywrócenie wyłącznie Postgres spowoduje uzyskanie instancji, do której można się zalogować, ale która będzie pusta. Należy również tworzyć kopie zapasowe bucketu MinIO, ponieważ przechowuje on surowe zdarzenia, które Langfuse utrwala w momencie nadejścia, co stanowi najbardziej wiarygodne źródło danych w tym stosie technologicznym.
Czy mogę skierować istniejącą konfigurację OpenTelemetry na samodzielnie hostowany Langfuse?
Tak. Langfuse w wersji v4 oraz jego obecne SDK bazują na OpenTelemetry, a instrumentacje OTel dla Anthropic i OpenAI eksportują dane bezpośrednio do niego. W języku Python należy wykonać pip install langfuse opentelemetry-instrumentation-anthropic, wywołać AnthropicInstrumentor().instrument() jednokrotnie przy starcie oraz ustawić LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY i LANGFUSE_BASE_URL na własny host. Przed rozpoczęciem poszukiwań brakującego dashboardu należy potwierdzić poprawność konfiguracji za pomocą langfuse.auth_check().