Як встановити Superlog для тріажу логів AI

Що насправді встановлює self-hosting Superlog

Щоб розгорнути Superlog самостійно, потрібно клонувати репозиторій, запустити Postgres, ClickHouse і OpenTelemetry collector через Docker Compose, виконати одну міграцію бази даних, а потім запустити чотири Node-сервіси з вихідного коду. Ваші застосунки надсилають трейси, журнали й метрики через OTLP (протокол OpenTelemetry) на порт приймання даних. Superlog обчислює їхні відбитки, об’єднує повторювані події в один інцидент, а агент створює початковий варіант тріажу. Встановлення займає один робочий день. Перед початком варто ознайомитися з обсягом компонентів і реальними обмеженнями.

Superlog поширюється за ліцензією Apache 2.0 і розміщений у github.com/superloglabs/superlog. Станом на August 2026 він має близько 1.2k зірок, приблизно 460 комітів у main і взагалі не має тегів релізів. Остання обставина впливає на встановлення: у git checkout v1.0.0 немає чого перевіряти, тому коміт потрібно зафіксувати самостійно або запускати ту версію, яка була в main на ранок, коли ви клонували репозиторій.

На які запитання відповідає Superlog, але не Uptime Kuma і Langfuse

Зовні self-hosted інструменти моніторингу здаються взаємозамінними. Це не так, і використання неправильного інструмента витрачає ресурси сервера без користі.

• Uptime Kuma перевіряє ваші кінцеві точки ззовні і відповідає на одне запитання: чи працює сервіс.
• Zabbix контролює хости й сервіси в Ubuntu 24.04, порівнюючи показники CPU, пам’яті, диска та стан сервісів із заданими порогами.
• Langfuse трасує виклики LLM, записуючи prompt, модель, кількість токенів, затримку та вартість кожного виклику.
• Superlog отримує телеметрію, яку вже передають ваші звичайні сервіси, і перетворює повторювані збої на інциденти.

Superlog відповідає на інше запитання: щось зламалося — що саме зламалося і чому. Він не орієнтований на виклики LLM і не перевіряє ваш сервіс ззовні. Superlog отримує OTLP зі звичайного коду застосунків і додає агента на етап первинного аналізу інциденту. Саме це і так зробив би черговий інженер під час першої перевірки.

Для бюджету VPS вирішальне значення має сховище. Uptime Kuma без проблем працює з 1 GB RAM, оскільки зберігає кілька тисяч результатів перевірок. Superlog використовує колоночне сховище, оскільки телеметрія записується один раз, а потім вибирається за часовим діапазоном із мільйонів рядків. Для цього призначений ClickHouse, а Postgres — ні. Postgres залишається в стеку та зберігає невеликий обсяг реляційних даних: проєкти, користувачів, інциденти й ключі ingest.

Що насправді запускає docker compose up -d?

Три контейнери, і жоден із них не є Superlog. Це дивує тих, хто очікує встановлення однією командою.

• postgres:16, опублікований на порту хоста 5434
• clickhouse/clickhouse-server:26.1, на порту 8123 для HTTP і 9000 для нативного протоколу
• otel/opentelemetry-collector-contrib:0.150.1, на порту 4317 для gRPC і 4318 для OTLP через HTTP

Застосунки Superlog працюють на хості з вихідного коду та запускаються через pnpm dev. Станом на August 2026 у репозиторії немає production compose-файлу, тому для тривалої експлуатації потрібні власні unit-файли systemd для кожного застосунку з його скриптом start або Dockerfile для окремих застосунків, які є в дереві репозиторію.

Тримайте в голові шлях, який проходить span, оскільки кожна наведена нижче помилка означає розрив на одній із його ланок. Ваш застосунок надсилає OTLP до intake-проксі Superlog. Проксі автентифікує запит за допомогою вашого ingest key, додає до нього project id і пересилає його до collector. Collector видаляє всі атрибути superlog.*, які намагався встановити клієнт, додає superlog.project_id із заголовка, переданого проксі, об’єднує дані в пакети та записує їх у ClickHouse. Вебзастосунок і API читають телеметрію з ClickHouse, а всі інші дані — з Postgres.

Таке видалення атрибутів є повноцінним засобом контролю multi-tenancy, а не декоративним налаштуванням. Без нього будь-хто, хто має дійсний ingest key, міг би самостійно встановити superlog.project_id і записати дані до іншого проєкту.

Якого розміру має бути VPS?

Для одного вузла за низького обсягу надходження даних закладіть 4 vCPU, 8 GB RAM і 40 GB SSD. Це мінімальний орієнтир для планування, а не результат вимірювання. Сприймайте його як початковий розмір і перевірте його відповідність власному трафіку.

Пам’ять використовується у чотирьох місцях. ClickHouse розрахований на машини з великим обсягом RAM, і його стандартні параметри це враховують. Postgres 16 у цій схемі споживає небагато ресурсів, оскільки зберігає метадані, а не телеметрію. Collector також споживає небагато ресурсів. А от чотири процеси Node — ні: сервер розробки Vite і три процеси tsx watch утримують по кілька сотень мегабайт кожен. Тому pnpm dev на машині з 2 GB RAM працює важко.

Диск — менш помітна проблема. pnpm install у цьому monorepo завантажує AWS SDK, клієнт ClickHouse, OpenTelemetry SDK і React toolchain ще до надходження першого span. Потім ClickHouse збільшується разом із вашим трафіком. Вимірюйте обидва показники:

df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"

За низького обсягу, коли кілька сервісів надсилають по кілька сотень span за хвилину, машина працює без значного навантаження, а ClickHouse більшість часу простоює. Проблему створює сплеск: невдалий deploy генерує тисячі однакових помилок за хвилину. Fingerprinting об’єднує їх в один incident для користувача, але ClickHouse все одно записує кожен рядок.

Тривалість зберігання визначаєте ви. ClickHouse exporter у collector створює таблиці, otel_traces, otel_logs і окрему таблицю для кожного типу метрик. Час автоматичного видалення застосовується лише тоді, коли конфігурація в infra/collector/config.yaml його задає. Дані не видаляються самостійно, тому активний місяць роботи заповнить диск, якщо не передбачити це заздалегідь.

Встановлення з фіксованого commit

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

git tag -l, який не виводить нічого, є очікуваним результатом станом на August 2026. Виберіть перевірений commit і використовуйте саме його:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Далі налаштуйте toolchain:

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json оголошує engines.node як >=20.0.0, а packageManager — як pnpm@9.12.0. Якщо виконати встановлення на старішій версії Node, pnpm завершить роботу з ERR_PNPM_UNSUPPORTED_ENGINE і вкаже потрібну версію. Пакет nodejs в архіві Ubuntu 24.04 старіший за 20, тому встановіть Node 20 або новішу версію з NodeSource або через nvm. У репозиторії є .nvmrc, тому nvm use вибере потрібну версію, якщо у вас встановлено nvm.

pnpm install
docker compose up -d
docker compose ps

Дочекайтеся завершення перевірок стану. Не вважайте up -d ознакою готовності. Postgres і ClickHouse мають такі перевірки у compose-файлі:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse відповідає на Ok., а pg_isready відповідає на accepting connections. Відмова в підключенні до 8123 означає, що контейнер ще запускається або завершив роботу. docker compose logs clickhouse показує, який саме випадок стався, а docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled повідомляє true, якщо kernel завершив процес через нестачу пам’яті. Це вказує на недостатній розмір сервера, а не на помилку конфігурації.

Далі виконайте міграцію та запустіть застосунки:

pnpm --filter @superlog/db db:migrate
pnpm dev

Зверніть увагу на порт: 5434, а не 5432. Compose-файл публікує Postgres на порту 5434, щоб він не конфліктував із Postgres, уже встановленим на host. Файли застосунку .env.example узгоджені з цим значенням через DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Якщо спрямувати міграцію на порт 5432 на сервері, де вже працює Postgres, ви отримаєте відмову в підключенні або, що гірше, застосуєте міграцію не до тієї бази даних.

pnpm dev запускає чотири процеси, перелічені в Procfile репозиторію: api, web, worker і proxy. Кожен процес передає свій вивід у tmp/logs/, тому tail -f tmp/logs/proxy.log — це місце, де слід моніторити ingest. У README web app працює на http://localhost:5173, API — на http://localhost:4100, а OTLP intake — на http://localhost:4101.

Перш ніж спрямовувати на них запити, перевірте, які порти фактично прослуховуються:

ss -lntp | grep -E '4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

Це стане важливо пізніше. Proxy читає власний порт зі змінної середовища PORT і використовує порт 4000, якщо PORT не задано. Development stack налаштовує цю змінну автоматично. Unit для systemd, який ви створюєте самостійно, цього не робить. Тому exporter, спрямований на порт 4101, коли proxy прослуховує порт 4000, завершується з помилкою відмови в підключенні без додаткових пояснень.

Надішліть один trace, створіть одну помилку, отримайте один інцидент

Створіть проєкт у вебзастосунку та скопіюйте його ключ ingest. Intake автентифікує кожен запит за цим ключем, тому телеметрія, надіслана без нього, не потрапляє до ClickHouse.

Спрямуйте будь-який OpenTelemetry SDK до intake за допомогою стандартних змінних середовища:

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'

Intake читає ключ із заголовка x-api-key, а також приймає authorization: bearer YOUR_INGEST_KEY, якщо ваш exporter простіше налаштувати саме так. Він обслуговує три стандартні шляхи OTLP: /v1/traces, /v1/logs і /v1/metrics, а також /health.

Варто назвати одну типову помилку. OTEL_EXPORTER_OTLP_ENDPOINT — це базова URL-адреса, і SDK додає до неї шлях сигналу. Спеціальні змінні для сигналів, наприклад OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, використовуються без змін, без додавання шляху. Якщо встановити спеціальну змінну для сигналу в http://127.0.0.1:4101, кожен export надсилатиметься на /. Це не маршрут, тому дані не надходять, а SDK записує помилку export, хоча застосунок працює нормально.

Для Node-сервісу достатньо варіанта без змін у коді, щоб перевірити весь конвеєр:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

Тепер навмисно зламайте щось. Підійде будь-який маршрут, який генерує помилку:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

Перевіряйте етапи по черзі, оскільки перший розрив показує, який етап не працює:

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

Зростання лічильника в otel_traces за порожнього вебзастосунку означає невідповідність проєкту. Перевірте, якому проєкту належить ключ ingest. Нульова динаміка лічильника за наявності активності в журналі проксі вказує на проблему в collector або під час запису до ClickHouse, тому перегляньте docker compose logs collector. Повна відсутність активності в журналі проксі означає, що exporter не досяг intake: неправильний порт, неправильний шлях або відхилений ключ.

У вебзастосунку ці повторювані помилки надходять як один інцидент, а не як окремий рядок для кожного запиту. Superlog обчислює fingerprint вхідних сигналів і групує відповідні сигнали. Саме тому inbox може містити одну сторінку з однією помилкою замість 4,000 однакових помилок. Потім agent записує результати розслідування поверх цієї групи.

Етап розслідування викликає model, тому для worker потрібно налаштувати model provider. Беріть назви цих змінних із файлу .env.example у каталозі кожного застосунку з commit, який ви зафіксували, а не з зовнішніх інструкцій, оскільки вони змінюються разом із main. Те саме стосується інтеграцій GitHub і Sentry: для них передбачені власні документи з налаштування за адресами docs/github-app-setup.md і docs/sentry-app-setup.md, а payload webhook описано в docs/webhooks.md.

Залиште intake приватним, а agent — лише для читання

Docker за замовчуванням публікує порти контейнерів на 0.0.0.0. Опубліковані порти обходять ufw, оскільки Docker записує власні правила в ланцюжок DOCKER-USER, які обробляються до того, як пакет потрапляє до ufw. На VPS із публічною IP-адресою compose-файл у початковій конфігурації відкриває ClickHouse HTTP на 8123 і Postgres на 5434 для доступу з інтернету. Облікові дані в цьому файлі є стандартними значеннями для розробки: користувач ClickHouse default без пароля та Postgres, де postgres використовується і як ім’я користувача, і як пароль.

Прив’яжіть їх до loopback. Кожен опублікований порт у compose-файлі отримує частину для хоста зі змінної середовища, тому достатньо створити .env у корені репозиторію:

POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318

Перевірте результат, перш ніж йому довіряти, а потім пересоздайте контейнери:

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

docker compose config виводить розгорнутий файл, тому можна перевірити 127.0.0.1:5434:5432, а не здогадуватися. Після цього ss має показувати 127.0.0.1:5434 і ніколи — 0.0.0.0:5434. Не намагайтеся виправити це за допомогою compose-файлу override, який повторно оголошує ports, оскільки Compose об’єднує списки портів з усіх файлів, а не замінює їх. У результаті ви отримаєте обидві прив’язки, і публічний порт усе ще залишатиметься відкритим.

Для intake потрібні такі самі заходи захисту. Ваш ingest key передається в заголовку, тому перед ним потрібен TLS (transport layer security): завершуйте TLS у nginx або Caddy перед проксі або залиште ingest у приватній мережі чи WireGuard-тунелі. Вебзастосунок на 5173 є сервером розробки Vite і взагалі не має бути доступним з інтернету.

Тепер про сам agent. Superlog позиціонує agent як засіб, що досліджує проблему та пропонує виправлення. Ключове слово тут — «пропонує». Залиште його в режимі лише для читання щодо production, доки не побачите його роботу на кількох реальних інцидентах. Надайте GitHub App дозволи лише на читання та дозвольте йому створювати pull request, які ви перевірятимете. Agent, який читає телеметрію та створює patch, є корисним. Agent, який може перезапускати ваші сервіси, створює зовсім інший рівень ризику. Це має бути свідоме рішення, а не доступ, отриманий за замовчуванням. Витрати потребують такої самої уваги, оскільки кожне дослідження є викликом до моделі: заздалегідь визначте бюджет на витрати agent на VPS, перш ніж спрямовувати його на гучну production-систему, і зберігайте запис фактичних дій agent, щоб за несподіваним pull request залишався audit trail.

Неполадки, з якими ви зіткнетеся, і рядки, що їх позначають

• ERR_PNPM_UNSUPPORTED_ENGINE під час pnpm install означає, що Node старіший за 20. node -v підтверджує це одним рядком.
• ECONNREFUSED 127.0.0.1:5434 під час міграції означає, що compose stack не запущений або DATABASE_URL указує неправильний порт.
• Циклічний перезапуск ClickHouse зазвичай означає проблему з пам’яттю. Прочитайте docker compose logs clickhouse, а потім перевірте, чи має контейнер OOMKilled значення true.
• Якщо exporter повідомляє про успіх, але вебзастосунок залишається порожнім, зазвичай це означає, що дані надійшли безпосередньо до collector на 4318. У такому разі пропускається додавання project, яке виконує proxy.
• Відмова в підключенні до 4101 у production-інсталяції означає, що proxy використав резервне значення PORT=4000. Явно задайте PORT у unit file.
• Якщо docker compose ps показує 0.0.0.0:8123, прив’язки до loopback не застосовуються. Виконайте docker compose config і прочитайте визначені порти.

Flawless, HyperProbe і місце Superlog

Ця категорія ще молода, а інструменти відрізняються тим, до чого агент має право отримувати доступ. Flawless — це open source AI SRE (site reliability engineering) інструмент для Kubernetes. Він читає дані з наявного стека Prometheus, Loki та Grafana, а не керує всім конвеєром. HyperProbe працює інакше: станом на August 2026 це hosted product із закритим вихідним кодом. Він розміщує probes лише для читання всередині запущеного процесу, щоб отримувати стан змінних, і передає цей стан assistant через MCP (model context protocol).

Superlog займає проміжне положення. Він керує всім конвеєром — від приймання OTLP до зберігання в ClickHouse — і використовує agent на етапі triage, а не на етапі виправлення. Саме тому self-hosting Superlog є інфраструктурним рішенням, а не контейнером, про який можна забути. Якщо ви запускаєте Superlog, ви запускаєте column store. Йому потрібне таке саме обслуговування, як і будь-якій іншій базі даних, якою ви керуєте.

FAQ

Скільки RAM потрібно для self-hosted Superlog?

Для одного вузла з невеликим обсягом надходження даних передбачте 8 GB RAM, 4 vCPU і 40 GB диска. Стек складається з Postgres, ClickHouse, колектора OpenTelemetry і чотирьох процесів Node, а ClickHouse потребує запасу ресурсів. VPS із 1 GB або 2 GB недостатньо: лише pnpm install споживає багато ресурсів, а під навантаженням ClickHouse завершується через OOM killer ядра. Виміряйте власні показники за допомогою docker stats --no-stream і free -m, а не покладайтеся на будь-які опубліковані значення, зокрема на наведене тут.

На який порт спрямовувати OTLP exporter?

На intake proxy Superlog, який у README налаштований на http://localhost:4101. Він обслуговує /v1/traces, /v1/logs і /v1/metrics та автентифікується за ingest key вашого проєкту, отриманим із заголовка x-api-key або заголовка authorization: bearer. Порт 4318 належить колектору OpenTelemetry під ним. Пряме надсилання даних на цей порт обходить proxy — саме proxy додає до даних ідентифікатор вашого проєкту. Якщо PORT не задано, proxy використовує порт 4000. Тому виконайте ss -lntp і перевірте, на якому порту він слухає, перш ніж припускати, що це 4101.

Чи замінює Superlog Uptime Kuma або Zabbix?

Ні. Uptime Kuma перевіряє ззовні вашої мережі, чи відповідає endpoint, а Zabbix відстежує показники хоста й сервісів за встановленими вами порогами. Superlog отримує traces, logs і metrics, які передають ваші застосунки, та об’єднує повторювані збої в інциденти. Використовуйте разом із ним зовнішню uptime-перевірку, оскільки probe в іншому місці все одно повідомить про збій, якщо саме сервер із вашим telemetry pipeline перестав працювати.

Чи може агент Superlog змінювати мої production-системи?

Лише в межах дозволів, які ви йому надаєте. Його результат — це розслідування та запропонована зміна, які перевіряє людина. Спочатку залиште GitHub App лише з read scopes, а pull requests — доступними для створення, і обмежте всі credentials, які має worker, правами на читання. Розглядайте write access до production як окреме рішення, яке потрібно ухвалювати свідомо: агент із можливістю перезапускати сервіси — це значно більша відповідальність, ніж агент, який читає telemetry та створює patch для перевірки.

Закріпити commit чи стежити за main?

Закріпіть commit. Станом на August 2026 у repository немає release tags, тому main — єдина доступна змінна ціль, і щотижня до неї додається кілька commits. Зафіксуйте SHA, який ви протестували, розгорніть саме його та перегляньте diff перед оновленням. git log --oneline <old-sha>..main містить опис перевірки, а файли .env.example для кожного застосунку — це перше місце, де слід шукати нові обов’язкові variables після будь-якого оновлення.