SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor · Оновлено 2026-11-06

Як self-host Superlog для AI-тріажу логів

Дізнайтеся, що насправді встановлює Superlog: Postgres, ClickHouse, OTLP collector і чотири Node-сервіси, а також як зафіксувати коміт без release tags.

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

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

Superlog поширюється за ліцензією Apache 2.0 і розміщений у github.com/superloglabs/superlog. Станом на 13 October 2026 він має близько 1.5k зірок, приблизно 490 комітів у main і взагалі не має release tags. Самостійно зафіксуйте потрібний коміт замість запуску тієї версії main, яка випадково була актуальною вранці, коли ви клонували репозиторій.

Які відповіді дає Superlog, але не дають Uptime Kuma та Langfuse

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

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

Для бюджету VPS важливе розрізнення стосується сховища. Superlog використовує column store, оскільки telemetry записується один раз, а потім вибирається за часовим діапазоном серед мільйонів рядків. Для цього призначений 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. Станом на 13 October 2026 у репозиторії немає compose-файлу для production, тому для тривалої експлуатації потрібні власні unit-файли systemd або Dockerfile для окремих застосунків, що входять до дерева файлів. Для застосунків api, worker і proxy передбачено скрипт start, який можна обгорнути в unit. Для web такого скрипту немає: це застосунок Vite, тому його потрібно зібрати за допомогою скрипту build і роздавати результат як статичні файли через nginx або Caddy, або запустити скрипт preview, який є vite preview.

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

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

Наскільки потужним має бути VPS?

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

Пам’ять використовується у чотирьох місцях. ClickHouse розрахований на системи з великим обсягом RAM, і його параметри за замовчуванням це враховують. Postgres 16 у цій схемі споживає небагато пам’яті, оскільки зберігає метадані, а не телеметрію. Collector також споживає небагато. Чотири процеси Node включають сервер розробки Vite і три процеси tsx watch. Виміряйте їхнє споживання пам’яті на власному сервері.

Диск є менш очевидною проблемою. 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"

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

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

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

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

Станом на 13 October 2026 команда git tag -l очікувано не виводить нічого. Виберіть перевірений коміт і використовуйте його:

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 не обов’язково зупиняє встановлення: перевірка engine залежить від конфігурації, а pnpm 9.12.0 виводить попередження, якщо engineStrict вимкнено. Пакет nodejs в архіві Ubuntu 24.04 старіший за версію 20, тому встановіть Node 20 або новішу версію з NodeSource чи за допомогою nvm. Репозиторій містить .nvmrc, тому nvm use вибирає потрібну версію, якщо у вас встановлено nvm.

pnpm install
docker compose up -d
docker compose ps

Дочекайтеся завершення health checks, а не вважайте 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 запускає turbo run dev. Він запускає скрипт dev кожного застосунку через Turborepo, зокрема api, web, worker і proxy, та виводить їхні журнали в одному терміналі. У репозиторії Procfile містить ті самі чотири процеси та передає вивід кожного з них до tmp/logs/. Якщо потрібно переглядати ingest у tail -f tmp/logs/proxy.log, запускайте застосунки через runner для Procfile, наприклад overmind або foreman, замість pnpm dev. У README для web app вказано http://localhost:5173, для API — http://localhost:4100, а для OTLP intake — http://localhost:4101.

Перед підключенням перевірте, який процес фактично прослуховує порт:

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

Це важливо на наступних етапах. Proxy читає власний порт зі змінної середовища PORT і використовує 4000, якщо PORT не задано. Файл apps/proxy/.env.example, який він завантажує, також задає PORT=4000, хоча в README для intake вказано 4101 (обидва значення перевірено 13 October 2026). Використовуйте порт, який показує ss. У прикладах нижче використано 4101, тому замініть його на 4000, якщо саме цей порт прослуховується. Створений вами unit systemd нічого не задає, якщо ви не додасте до нього PORT. Тому exporter, спрямований на 4101, коли proxy прослуховує 4000, завершується з відмовою в підключенні без додаткових пояснень.

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

Створіть проєкт у вебзастосунку та скопіюйте його ingest key. 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 достатньо варіанта без змін у коді, щоб перевірити весь pipeline:

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 key. Якщо значення не змінюється, але в журналі проксі є активність, проблема, імовірно, у collector або записі до ClickHouse. Перегляньте docker compose logs collector. Якщо в журналі проксі немає жодної активності, exporter не досяг intake: неправильний порт, неправильний шлях або відхилений ключ.

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

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

Залиште intake приватним, а agent — у режимі read only

Docker за замовчуванням публікує порти контейнерів на 0.0.0.0, і такі опубліковані порти обходять ufw. Docker маршрутизує трафік контейнерів у таблиці nat, тому пакет до опублікованого порту перенаправляється ще до того, як досягає ланцюжків INPUT і OUTPUT, де зберігаються правила ufw. У результаті ufw не може вплинути на цей трафік. На VPS із публічною IP-адресою файл compose у початковому вигляді відкриває ClickHouse HTTP на порту 8123, а Postgres — на порту 5434. Через інтернет до них можна підключитися. Облікові дані у цьому файлі є development defaults: користувач 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. Просте повторне оголошення ports у файлі Compose override зберігає обидві прив’язки, якщо IP-адреса хоста відрізняється. У Compose 2.24.4 і новіших версіях для заміни списку можна використовувати ports: !override.

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

Тепер про сам agent. Superlog позиціонує agent як засіб, що досліджує проблему та пропонує виправлення. Важливе слово тут — пропонує. Залишайте його в режимі read only щодо production, доки не переконаєтеся в його роботі на кількох реальних інцидентах. Read-only GitHub App не може передати fix branch або створити pull request: setup guide вимагає дозволів Contents і Pull requests з правом запису для цього workflow, а також Issues з правом запису для коментарів. Agent, який читає telemetry та записує patch, може бути корисним. Agent, який може перезапускати ваші сервіси, створює інший рівень ризику. Таке рішення потрібно приймати свідомо, а не успадковувати як значення за замовчуванням. Під час налаштування model-backed runner так само враховуйте витрати: сплануйте бюджет витрат agent на VPS до того, як спрямовувати його на гучну production-систему, і зберігайте запис фактичних дій agent, щоб неочікуваний pull request мав audit trail.

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

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

Flawless, HyperProbe і місце Superlog

Ця категорія ще молода, а інструменти відрізняються тим, до яких компонентів агент може отримувати доступ. Репозиторій Flawless тепер представляє CISRE — AI-платформу SRE (site reliability engineering) для Kubernetes і хмарної інфраструктури — за ліцензією PolyForm Noncommercial. HyperProbe розміщує probes у запущеному процесі, щоб отримувати стан змінних, і передає цей стан асистенту через MCP (model context protocol). Також у документації описано self-hosting за допомогою Docker Compose і license key.

Superlog займає проміжне положення між ними. Він керує всім pipeline: від приймання 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 потребує запасу ресурсів. Вимірюйте власні показники за допомогою 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, який додає до даних ідентифікатор вашого проєкту. Якщо PORT не задано, proxy використовує порт 4000. Його .env.example також задає порт 4000, тому виконайте ss -lntp і перевірте, на якому порту він прослуховує з’єднання, перш ніж припускати, що це 4101.

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

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

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

Лише в межах дозволів, які ви йому надасте. Стандартний community runner записує локальний підсумок incident; інші investigation runtimes залежать від налаштованого вами runner. Обмежте production credentials правами читання. Створення pull requests потребує окремих GitHub write permissions для branches і pull requests. Надавайте write access до production лише після окремого свідомого рішення, оскільки agent, який може перезапускати сервіси, є значно більшою відповідальністю, ніж agent, який читає telemetry і готує patch для перевірки.

Чи слід зафіксувати commit або відстежувати main?

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

Чи була ця стаття корисною?