Langfuse на власному VPS: розгортання та TLS
Розгорніть Langfuse на власному VPS: мінімальні ресурси, pinned image tags, TLS, retention для ClickHouse до заповнення диска та робочі backups.
Навіщо взагалі відстежувати роботу AI-агента
Ви розгортаєте Langfuse на власному сервері, щоб бачити, що саме агент зробив під час запуску. Langfuse — це open source інструмент observability для LLM (large language model). Він записує кожен prompt, кожну відповідь моделі, кожен виклик інструмента та кожен token, а потім об’єднує їх в один trace, який можна відкрити й переглянути. Якщо запускати його на власному VPS, ці prompt не залишають сервер, яким ви керуєте.
Причина проста. Неможливо виправити проблему з витратами або якістю, якої ви не бачите. Рахунок від провайдера показує, що у вівторок витрати були вчетверо більшими, ніж у понеділок. Trace показує, який запуск агента це спричинив, який prompt виріс до 40,000 token і який цикл повторних спроб виконався дев’ять разів, перш ніж завершитися помилкою. Рахунок дає число. Trace показує код, який це число сформував.
У цьому посібнику використовуються три терміни. Trace — це один повний запуск агента від початку до кінця. Observation — це один крок у межах такого запуску: span для звичайного коду або generation для виклику моделі. Score — це число, пов’язане з trace, отримане під час перевірки людиною або автоматизованим evaluator. Langfuse підтримує OpenTelemetry (OTel) — нейтральний щодо постачальників стандарт для розподіленого tracing, тому наявну instrumentation можна спрямувати до нього.
Що насправді запускає self-hosted Langfuse
Langfuse v4 — це не один контейнер. Це два контейнери застосунків і чотири сервіси зберігання. На одному VPS усі шість компонентів працюють на вашому сервері.
langfuse-webобслуговує вебінтерфейс і API приймання даних.langfuse-workerу фоновому режимі обробляє чергу. Він розбирає пакети даних, обчислює вартість і запускає нічне завдання очищення за політикою зберігання.- Postgres зберігає транзакційні дані, зокрема користувачів, організації, проєкти, API keys і prompts.
- ClickHouse зберігає самі trace-дані, тобто observations і scores. Це column store для аналітичних запитів. Тому dashboard для понад ста мільйонів рядків усе ще відповідає швидко.
- Redis — це черга та cache між web і worker.
- MinIO надає S3-сумісне object storage на сервері. Він зберігає кожну необроблену вхідну подію, а також усі media-файли, які ви додаєте.
Langfuse публікує мінімальні ресурси для кожного компонента, який запускає. На схемі показано три компоненти, що виконують основну роботу.
Дані, на яких побудовано графік
[
{
"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 потребує 8 GiB пам’яті. Web container і worker потребують по 4 GiB кожен. Це опубліковані мінімальні значення для 3 компонентів на схемі. На тій самій сторінці для Postgres указано 4 GiB, для Redis або Valkey — 1.5 GiB, а для MinIO — 4 GiB. Отже, мінімальні вимоги для всіх шести компонентів разом становлять 25.5 GiB. У власному посібнику проєкту з Docker Compose рекомендовано щонайменше 4 cores, 16 GiB пам’яті та приблизно 100 GiB storage для однієї машини. Це менше за суму мінімальних вимог компонентів. Тому вважайте 16 GiB мінімумом для shared Compose-сервера, а не запасом ресурсів.
Не запускайте це на тарифі з 2 GiB. ClickHouse запускається і певний час приймає записи, а потім завершує роботу під час background merge, оскільки merge завантажує великі частини таблиці в пам’ять. Ви побачите, що docker compose ps показує clickhouse container як restarting, dmesg містить рядок на кшталт Out of memory: Killed process 1234 (clickhouse-serv), а кожен Langfuse dashboard повертає 500. За меншого навантаження ClickHouse натомість відхиляє запит і записує в журнал DB::Exception: Memory limit (total) exceeded. Плануйте щонайменше 16 GiB. Якщо на цьому самому VPS мають працювати інші сервіси, закладайте ресурси для них окремо, оскільки навіть порівняно легкий stack, як self-hosted робочий простір AFFiNE, потребує власних гігабайтів, а ClickHouse не поверне вам зайняту пам’ять.
Розгорніть Langfuse за допомогою Docker Compose
Клонуйте репозиторій. Стек, його компоненти та середовище за замовчуванням зберігаються у docker-compose.yml.
git clone https://github.com/langfuse/langfuse.git
cd langfuseУсі значення, які потрібно змінити, позначені в цьому файлі як # CHANGEME. Спочатку згенеруйте три секрети застосунку.
openssl rand -base64 32 # NEXTAUTH_SECRET
openssl rand -base64 32 # SALT
openssl rand -hex 32 # ENCRYPTION_KEYENCRYPTION_KEY має містити 256 бітів, записаних як 64 шістнадцяткові символи. Саме такий результат виводить openssl rand -hex 32. Цей ключ шифрує конфіденційні значення під час зберігання, зокрема ключі LLM-провайдерів, які ви зберігаєте в інстансі. Якщо змінити його після появи даних, ці записи більше неможливо буде розшифрувати. Тому вважайте його незмінним від першого запуску. SALT використовується для хешування API-ключів Langfuse. Якщо змінити це значення, усі ключі, якими вже користуються ваші агенти, стануть недійсними.
Потім задайте POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH і MINIO_ROOT_PASSWORD. Пароль MinIO з’являється в чотирьох місцях: спочатку як MINIO_ROOT_PASSWORD, а потім як LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY і LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Якщо пропустити хоча б одне місце, MinIO відхилить запит цього клієнта з помилкою SignatureDoesNotMatch. Вона з’явиться в журналі worker, хоча вебінтерфейс і далі може працювати нормально. Зберігання цих значень в env-файлі, а не у відстежуваному compose-файлі, описано в розділі env-файли та секрети Docker Compose.
Зафіксуйте теги образів перед запуском
Файл, що постачається, використовує docker.langfuse.com/langfuse/langfuse:4 і docker.langfuse.com/langfuse/langfuse-worker:4. Ці теги змінюються. Langfuse автоматично виконує міграції Postgres і ClickHouse під час запуску. Тому звичайний docker compose pull через кілька місяців може перетворитися на незаплановану міграцію схеми бази даних, резервну копію якої ви не створили того ранку. Зафіксуйте обидва образи на одному релізі у docker-compose.override.yml. Compose накладає цей файл поверх файла, що постачається, тому наступний git pull не перезапише ваші зміни. Ті самі образи публікуються на Docker Hub, звідки їх завантажує наведений нижче override-файл.
services:
langfuse-web:
image: docker.io/langfuse/langfuse:4.72.0
langfuse-worker:
image: docker.io/langfuse/langfuse-worker:4.72.0Версія 4.3.1 була актуальною версією гілки 4.3 станом на August 2026. Відтоді релізи виходили часто, а станом на October 11, 2026 найновішою версією на GitHub була v4.56.0. У наведеному вище override-файлі використовується v4.72.0 — найновіша версія на GitHub станом на October 31, 2026. Перевірте сторінку релізів проєкту на GitHub, зафіксуйте версію, актуальну в день розгортання, а потім змінюйте це число свідомо. Деякі storage images у файлі, що постачається, також варто зафіксувати, оскільки їхні теги теж змінюються. postgres:17 (значення за замовчуванням змінної POSTGRES_VERSION) і redis:7 відповідають major version. Тепер у файлі, що постачається, для docker.io/clickhouse/clickhouse-server використовується точний тег версії, який фіксує конкретну версію ClickHouse. Це правило стосується не лише Langfuse: self-hosted трекер тренувань openGym використовує лише частину цього стеку, але також потребує іменованого git-тега, оскільки будь-який компонент, який мігрує власну базу даних під час запуску, може перетворити звичайне завантаження образу на зміну схеми.
Запустіть стек.
docker compose up -d
docker compose ps
docker compose logs -f langfuse-workerПід час першого запуску виконуються міграції, тому зачекайте дві або три хвилини, перш ніж перевіряти доступність сервісів. Після запуску вебконтейнер один раз записує в журнал Ready. docker compose ps має показати шість сервісів у стані running. Якщо контейнер постійно перезапускається, причина буде в його журналі. Міграції ClickHouse виконуються під час запуску вебконтейнера, тому неправильне значення CLICKHOUSE_MIGRATION_URL з’явиться у docker compose logs langfuse-web, а не в журналі worker, який ви переглядаєте. Ця змінна використовує нативний протокол ClickHouse на порту 9000, а не HTTP-порт 8123. Якщо вказати порт 8123, запускові міграції вебконтейнера завершаться помилкою. Worker виконує повільніші фонові міграції, тому повідомлення про них потрібно шукати в його журналі.
Перевірте стан безпосередньо з сервера.
curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/readyЗвичайний виклик /api/public/health лише підтверджує, що API-процес працює, оскільки за замовчуванням він не перевіряє базу даних. Варіант failIfDatabaseUnavailable=true підходить для моніторингу: він повертає 503, якщо база даних недоступна. /api/public/ready повертає 200, коли вебконтейнер готовий приймати мережевий трафік, і 500 після отримання команди на завершення роботи. Обидві перевірки є звичайними HTTP-перевірками, тому сторінка стану Uptime Kuma може моніторити їх і повідомити, що стек недоступний, ще до того, як це виявлять ваші агенти.
Використайте TLS і закрийте додаткові порти
Наданий файл compose публікує 3000:3000 для web-контейнера та 9090:9000 для MinIO. Обидва порти прив’язані до всіх інтерфейсів. На публічній IP-адресі це означає, що будь-хто, хто просканує порт 3000, побачить сторінку реєстрації, а той, хто просканує 9090, отримає доступ до bucket із вашими необробленими prompts.
Самого правила firewall недостатньо, щоб закрити ці порти. Docker записує власні правила DNAT у таблицю nat. Вони обробляються до того, як пакет потрапить до правил фільтрації ufw, тому ufw deny 3000 залишає опублікований порт відкритим. Ця проблема настільки поширена, що для неї є окремий посібник: чому опубліковані Docker порти обходять ufw. У файлі override прив’яжіть порти до loopback. Використовуйте !override з Docker Compose 2.24.4 або новішою версією, щоб замінити опубліковані порти. Звичайний список об’єднується з початковими прив’язками.
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 має містити точну публічну адресу разом зі схемою, оскільки flow входу формує callback URL на основі цього значення. Якщо за HTTPS-проксі залишити http://localhost:3000, після входу браузер буде перенаправлено на адресу, до якої він не може підключитися.
Тепер налаштуйте reverse proxy на 127.0.0.1:3000 і передайте йому керування сертифікатом. Для Traefik у тому самому Compose-проєкті маршрутизуйте запити до langfuse-web:3000 через Compose network, використовуючи labels, описані в розділі як запустити кілька застосунків за одним reverse proxy Traefik. Якщо Langfuse — єдиний сервіс на сервері, Caddy виконує це завдання двома рядками. Перевірте конфігурацію за допомогою curl -sI https://langfuse.example.com/api/public/ready, а потім з іншої машини переконайтеся, що curl http://YOUR_IP:3000 не приймає з’єднання.
Є один нюанс із MinIO. Langfuse передає presigned URLs із посиланням на цей S3 endpoint: SDK, які завантажують медіа, і браузеру, який їх відкриває. Тому якщо ви використовуєте multi-modal traces із зображеннями або аудіо, MinIO, доступний лише через loopback, не дасть змоги завантажувати ці вкладення з інших машин або відкривати їх у браузері. Перед налаштуванням проксі прочитайте сторінку про конфігурацію blob storage, оскільки endpoint у presigned URL, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, має відповідати опублікованій адресі. Звичайні текстові traces це не зачіпає.
Створіть обліковий запис під час першого входу, а потім обмежте доступ до інстансу. Після створення облікового запису один раз задайте AUTH_DISABLE_SIGNUP=true, щоб сторонні користувачі, які відкриють сторінку, взагалі не могли реєструватися. Langfuse також має LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, який обмежує коло користувачів, що можуть створювати організації. Однак це функція Enterprise Edition, яка працює лише з license key. Якщо ви вже використовуєте Authentik як власний identity provider, Langfuse підтримує стандартне OIDC-підключення. Тоді облікові записи створюються та видаляються разом з іншими вашими застосунками, а не зберігаються в окремому списку паролів, відомому лише цьому серверу.
Надішліть перший trace
Створіть project у web interface та скопіюйте його public і secret keys у project settings. Python SDK читає три 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 — це назва змінної в SDK v4, випущеному в March 2026. Старий код і старі інструкції використовують LANGFUSE_HOST. Якщо ваші traces потрапляють у Langfuse Cloud замість вашого сервера, причина — не заданий base URL, оскільки за замовчуванням використовується hosted instance.
Поточний Python SDK v5 потребує Python 3.11 або новішої версії та self-hosted Langfuse v4.59.0 або новішої версії. Версія сервера, зафіксована вище, відповідає цій вимозі.
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()Декоратор @observe створює observation навколо функції, захоплює її аргументи та значення, яке вона повертає, і вкладає observation у вже активний observation. AnthropicInstrumentor — це OpenTelemetry instrumentation для клієнта Anthropic. Вона перетворює кожен виклик messages.create на generation із назвою моделі, token usage і latency без змін у місці виклику.
Дві функції виконують перевірку замість вас. langfuse.auth_check() повертає False для неправильних keys або неправильного base URL. Це швидше, ніж з’ясовувати, чому dashboard порожній. langfuse.flush() блокує виконання, доки queued spans не буде надіслано. Це потрібно для процесів із коротким часом роботи, оскільки SDK надсилає дані пакетами у фоні, а скрипт, який одразу завершується, втрачає невідправлений пакет. Якщо traces надсилає вся команда, а не один скрипт, задайте ці три змінні один раз у gateway, через який уже проходять агенти всіх користувачів, замість того щоб задавати їх у shell кожного користувача. Саме так self-hosted OneCLI harness забезпечує instrumentation запусків усіх колег, а keys залишаються в одному місці.
Чому ClickHouse постійно займає дедалі більше місця?
Трейси — це дані, які найшвидше зростають у більшості self-hosted інсталяцій. Кожен запуск агента записує один рядок для кожного кроку. Вхідні та вихідні дані зберігаються повністю. Тому балакучий агент із довгими промптами генерує за день значно більше байтів, ніж застосунок, роботу якого він відстежує. Якщо нічого не змінювати, ClickHouse заповнить диск. Заповнений диск зупиняє запис даних, а не просто сповільнює його.
Тут зростають дві окремі категорії даних. Для кожної потрібне окреме рішення.
Перша категорія — ваші власні дані трейсів. Для них потрібно налаштувати retention. У self-hosted інсталяції зберігання даних протягом визначеного періоду є функцією Enterprise Edition і потребує license key. Без нього Langfuse зберігає трейси, observations, scores і media безстроково. Тому розрахуйте диск із урахуванням цього та використовуйте disk alert наприкінці цього розділу. Якщо license key є, власники проєктів і адміністратори відкривають налаштування проєкту та задають період зберігання даних у днях. Langfuse приймає мінімальне значення 3 дні. Після цього нічне завдання вибирає трейси, observations, scores і media assets, старші за вказаний період, і видаляє їх із ClickHouse та blob storage. Виняток — media, пов’язані зі збереженими елементами dataset. Для виконання завдання потрібен дозвіл DeleteObject на bucket. Облікові дані root для MinIO у стандартному compose file вже мають цей дозвіл. Видалення є незворотним, тому спочатку налаштуйте blob storage export, якщо вам потрібна історія за тривалий період. Не додавайте вручну TTL clauses до власних таблиць Langfuse. Саме retention job синхронізує ClickHouse і bucket. Ручний TTL видаляє дані лише з одного боку.
Вибирайте період з урахуванням фактичного використання даних. Перевірка вартості та якості зазвичай виконується для даних за останні дні, а не місяці. Для невеликої команди розумно почати з 30 днів. Якщо ви відкриваєте trace лише після виникнення проблеми, достатньо 14 днів.
Друга категорія — власні system log tables ClickHouse. Це часто стає несподіванкою, оскільки диск продовжує заповнюватися навіть після налаштування retention. ClickHouse записує trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log і latency_log для власної діагностики. Для цих таблиць за замовчуванням не задано TTL, а Langfuse їх не читає. Спочатку визначте, куди фактично витрачається місце на диску.
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
)Запустіть команду з docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Якщо system tables перебувають близько до початку списку, вимкніть їх за допомогою config overlay. ClickHouse під час запуску об’єднує кожен файл із /etc/clickhouse-server/config.d/ з основною конфігурацією.
<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>Підключіть цей файл і перезапустіть ClickHouse.
services:
clickhouse:
volumes:
- ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:roЦе зупинить нові записи. Рядки, які вже зберігаються на диску, залишаться там. Тому звільніть місце явно за допомогою DROP TABLE IF EXISTS system.trace_log і виконайте те саме для кожної видаленої таблиці. Якщо ви хочете зберегти діагностичні дані, замість remove="1" можна налаштувати агресивний TTL для кожної таблиці. Це описано в документації Langfuse з масштабування. Ці TTL directives застосовуються лише під час першого створення system table. Тому для наявної інсталяції в цій самій документації також описано, як додати TTL до вже створених таблиць.
Є ще одна таблиця, про яку варто знати. blob_storage_file_log відстежує event files, завантажені до вашого bucket. Якщо для bucket також налаштовано lifecycle policy, задайте для таблиці відповідний TTL, щоб ці налаштування не розходилися.
ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;Також додайте звичайний df -h alert для data disk. Трейси зростають нерівномірно. Різке зростання може початися в день, коли ви розгортаєте нового агента. Першою ознакою цього не має бути збій запису даних.
Резервне копіювання Postgres і ClickHouse
Резервна копія Langfuse складається з трьох частин. Postgres зберігає користувачів, організації, проєкти та API keys. ClickHouse зберігає traces. MinIO зберігає raw events. Якщо відновити лише Postgres, ви отримаєте робочий вхід без історії. Якщо відновити лише ClickHouse, ви отримаєте історію, яку ніхто не зможе переглянути без входу. Такий поділ характерний не лише для Langfuse: self-hosted служба підтримки Chatwoot має таку саму структуру, коли дамп Postgres без каталогу uploads відновлює розмови, але всі вкладення в них втрачаються.
Postgres — це звичайний pg_dump, який використовують у документації Langfuse з резервного копіювання для Docker-інсталяції.
docker compose exec -T postgres pg_dump -U postgres postgres \
| gzip > langfuse-pg-$(date +%F).sql.gzДля ClickHouse потрібно більше уваги, оскільки копіювання каталогу даних під час виконання merge-операцій не створює узгодженої резервної копії. Простий підхід на одному сервері — зупинити контейнер і заархівувати 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 clickhouseВикористовуйте назву volume, яку виводить docker volume ls, а не назву, записану в YAML. Файл оголошує langfuse_clickhouse_data, а Compose додає до неї префікс із назви проєкту, тому клон у каталозі з назвою langfuse створює langfuse_langfuse_clickhouse_data. Якщо вказати неправильну назву, docker run без повідомлення про помилку створить новий порожній volume, і ваш архів не міститиме даних.
Langfuse завантажує raw event data у bucket під час кожного запиту ingestion і повторно читає їх, щоб повторити невдалі ingestion jobs. Тому коротка зупинка ClickHouse здебільшого означає, що worker повторить обробку пізніше. Виконуйте це в період низького навантаження та зупиняйте сервіс на якомога коротший час. Для завантаженого екземпляра власна інструкція BACKUP DATABASE default TO S3(...) у ClickHouse створює узгоджену резервну копію без зупинки сервера. MinIO — третя частина, і для неї підходить mc mirror або реплікація MinIO до bucket на іншому сервері. Незалежно від вибраного способу, зберігайте результат за межами сервера — для цього призначені зашифровані резервні копії restic на VPS.
Redis зберігає чергу та cache. Його втрата видаляє jobs, що перебувають у черзі, навіть якщо їхні raw event files залишилися в bucket.
Застереження щодо узгодженості є важливим. Postgres і ClickHouse створюють дампи в різні моменти, тому після відновлення може залишитися рядок проєкту без traces або traces, що належать проєкту, якого вже не існує. Langfuse допускає такий стан, але створюйте обидва дампи з мінімальним інтервалом і в період низького трафіку. Bucket подій є основною гарантією збереження даних, оскільки Langfuse завантажує raw event data туди під час кожного запиту ingestion.
Хоча б один раз відновіть дані в тестовому стеку. Так ви виявите неправильну назву volume зараз, а не під час аварії.
На що звернути увагу спочатку
Першого тижня зосередьтеся на чотирьох показниках.
- Вартість одного trace. Langfuse обчислює вартість за назвою моделі та використанням токенів. Відсортуйте trace за вартістю й повністю перегляньте найдорожчий. Зазвичай причина — надмірно розрослий prompt: у контекст вставлено цілий документ або історію розмови ніхто не скорочує. Коли це видно, контроль витрат на AI agent стає інженерним завданням, а не припущенням.
- Розподіл використання токенів між input і output. Input-токенів багато, і вони дешеві. Output-токенів мало, але вони дорогі. Кешований input коштує ще дешевше. Цю саму систему обліку детально описано в матеріалі як обліковується використання токенів у Claude Code. Вона також застосовна до будь-якого agent, якого ви напишете самостійно.
- Перцентилі затримки. Медіана приховує проблему. Саме на рівнях p95 і p99 виникають timeouts. У циклі agent повільний виклик tool на рівні p95 множиться на кількість ітерацій.
- Невдалі виклики tool. Відфільтруйте observations за рівнем
ERROR. Tool, який завершується помилкою у 5% випадків, непомітний у загальному показнику успішності, але добре помітний у trace: модель повторює спробу, а потім витрачає токени на обхід проблеми.
Встановіть період зберігання даних і виберіть dashboard, який перевірятимете щотижня в той самий день, коли виконуєте deployment. Інструмент observability, який ніхто не відкриває, перетворюється на базу даних, що заповнює диск.
FAQ
Скільки пам’яті потрібно для self-hosted Langfuse?
Передбачте 4 ядра CPU і 16 GiB пам’яті. Саме таку конфігурацію рекомендує інструкція Langfuse Docker Compose для однієї віртуальної машини. Також потрібно близько 100 GiB дискового простору. Опубліковані мінімальні вимоги компонентів становлять 8 GiB для ClickHouse і по 4 GiB для контейнерів web і worker. На цій самій сторінці вказано 4 GiB для Postgres, 1.5 GiB для Redis і 4 GiB для MinIO. Отже, усі шість компонентів разом потребують 25.5 GiB, що перевищує рекомендацію 16 GiB для Compose.
Чому диск ClickHouse продовжує заповнюватися після налаштування зберігання даних?
Налаштування зберігання поширюється лише на власні дані Langfuse. ClickHouse окремо записує діагностичні таблиці trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log і latency_log, для яких TTL не налаштовано. Виконайте запит system.parts з групуванням за таблицею, щоб визначити найбільшу таблицю. Потім вимкніть непотрібні таблиці за допомогою запису remove="1" у файлі в каталозі /etc/clickhouse-server/config.d/, перезапустіть ClickHouse і видаліть наявні таблиці, щоб звільнити вже зайнятий простір.
Який мінімальний період зберігання даних у Langfuse?
Три дні. Період зберігання налаштовується окремо для кожного проєкту в налаштуваннях проєкту або через Organization Management API. Щоночі окреме завдання видаляє з ClickHouse і blob storage traces, observations, scores і media assets, старші за встановлений період. Виняток становлять media, пов’язані зі збереженими dataset items. У self-hosted інсталяції це функція Enterprise Edition, для якої потрібен license key. Без нього дані зберігаються необмежено. Видалення неможливо скасувати, тому спочатку налаштуйте експорт у blob storage, якщо потрібна історія за межами цього періоду.
Чи потрібно створювати резервні копії і Postgres, і ClickHouse?
Так, оскільки вони зберігають різні дані. Postgres містить користувачів, організації, проєкти та API keys, а ClickHouse — самі trace data. Відновлення лише Postgres дасть змогу увійти в інсталяцію, але вона буде порожньою. Також створюйте резервну копію MinIO bucket, оскільки в ньому зберігаються raw events, які Langfuse записує під час отримання. У цій архітектурі це найближчий аналог джерела істини.
Чи можна підключити наявне налаштування OpenTelemetry до self-hosted Langfuse?
Так. Langfuse v4 і його поточні SDK побудовані на OpenTelemetry, а інструментації Anthropic і OpenAI OTel експортують дані безпосередньо до нього. У Python виконайте pip install langfuse opentelemetry-instrumentation-anthropic, один раз викличте AnthropicInstrumentor().instrument() під час запуску та встановіть LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY і LANGFUSE_BASE_URL для власного хоста. Перед пошуком проблеми з відсутнім dashboard перевірте результат за допомогою langfuse.auth_check().