Автор: Matt Connor 2026-08-06 · Обновлено 2026-08-07

Как установить Superlog для анализа логов через AI

Q: На какой порт направлять экспортер OTLP?

На прокси приема Superlog, который в README указан как http://localhost:4101. Он обслуживает /v1/traces, /v1/logs и /v1/metrics, а аутентификация происходит по ключу приема вашего проекта, который берется из заголовка x-api-key или authorization: bearer. Порт 4318 принадлежит коллектору OpenTelemetry, работающему «под капотом»; прямая отправка данных туда минует прокси, который отвечает за присвоение идентификатора проекта вашим данным. Если переменная PORT не задана, прокси использует порт 4000, поэтому выполните ss -lntp и проверьте, на каком порту он запущен, прежде чем считать, что это 4101.

Узнайте, как развернуть Superlog на собственном VPS для автоматической сортировки OTLP трассировок и метрик. Инструкция по настройке Docker Compose и запуску Node сервисов.

Что именно устанавливается при self-hosting Superlog

Для self-hosting Superlog необходимо клонировать репозиторий, запустить Postgres, ClickHouse и OpenTelemetry collector через Docker Compose, выполнить одну миграцию базы данных, а затем запустить четыре Node-сервиса из исходного кода. Ваши приложения отправляют трассировки, логи и метрики по протоколу OTLP (OpenTelemetry protocol) на порт приема данных, Superlog создает их отпечатки (fingerprints), группирует повторяющиеся события в один инцидент, а агент выполняет первичную сортировку (triage). Установка занимает вторую половину дня. Перед началом работы стоит ознакомиться с требованиями к ресурсам и реальными ограничениями системы.

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

На какие вопросы отвечает Superlog, в отличие от Uptime Kuma и Langfuse

Самохостинг-инструменты мониторинга кажутся взаимозаменяемыми, если смотреть на них со стороны. Это не так, и использование неподходящего решения приводит к потере ресурсов сервера без какой-либо пользы.

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

Superlog отвечает на другой вопрос: что-то сломалось — что именно и почему. У него нет функций для анализа вызовов LLM, и он не опрашивает сервисы извне. Он принимает OTLP из кода вашего приложения и размещает агента на этапе первичной сортировки (triage), которую в любом случае первым делом выполняет дежурный инженер.

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

Что на самом деле запускает 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. По состоянию на август 2026 года в репозитории нет compose-файла для production, поэтому для долгосрочной установки потребуются собственные systemd-юниты для каждого скрипта start приложения или использование Dockerfile, поставляемых в дереве исходного кода для каждого компонента.

Держите в уме путь, который проходит спан, так как любой сбой ниже означает разрыв на одном из этапов. Ваше приложение отправляет OTLP в прокси-приемник Superlog. Прокси аутентифицирует запрос с помощью вашего ключа приема (ingest key), помечает его идентификатором проекта и пересылает коллектору. Коллектор удаляет любые атрибуты superlog.*, которые клиент пытался задать, добавляет superlog.project_id из заголовка, предоставленного прокси, группирует данные и записывает их в ClickHouse. Затем веб-приложение и API считывают телеметрию из ClickHouse, а всё остальное — из Postgres.

Это удаление атрибутов является реальным механизмом контроля мультиарендности, а не просто декорацией. Без него любой, у кого есть один валидный ключ приема, мог бы самостоятельно задать superlog.project_id и записывать данные в чужой проект.

Каким должен быть размер VPS?

Для установки на одном узле при небольшом объеме входящих данных планируйте конфигурацию с 4 vCPU, 8 GB RAM и 40 GB SSD. Это минимальный расчетный уровень, а не точное измерение, поэтому рассматривайте его как стартовую точку и корректируйте в соответствии с вашим реальным трафиком.

Оперативная память распределяется между четырьмя компонентами. ClickHouse спроектирован для работы на машинах с большим объемом RAM, и его настройки по умолчанию исходят из этого. Postgres 16 потребляет меньше ресурсов, так как хранит метаданные, а не телеметрию. Коллектор также нетребователен. Четыре процесса Node — это другое дело: сервер разработки Vite и три процесса tsx watch занимают сотни мегабайт каждый, поэтому pnpm dev на машине с 2 GB RAM работает крайне медленно.

Дисковое пространство — менее очевидная проблема. pnpm install в этом монорепозитории загружает AWS SDK, клиент ClickHouse, OpenTelemetry SDK и инструментарий React еще до того, как вы получите первый 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 большую часть времени простаивает. Нагрузка, которая создает проблемы, — это всплески: неудачное развертывание, генерирующее тысячи идентичных ошибок в минуту. Механизм формирования отпечатков (fingerprinting) объединяет их в один инцидент для пользователя, но ClickHouse все равно записывает каждую строку в базу данных.

Период хранения данных вы определяете самостоятельно. Экспортер ClickHouse в коллекторе создает таблицы otel_traces, otel_logs и по одной таблице на каждый тип метрик. Время жизни данных (TTL) применяется только в том случае, если оно задано в конфигурации infra/collector/config.yaml. Никакие данные не удаляются автоматически, поэтому за активный месяц диск может заполниться, если вы не настроите политику хранения заранее.

Установка из зафиксированного коммита

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

git tag -l отсутствие вывода — ожидаемый результат по состоянию на август 2026 года. Выберите коммит, который вы протестировали, и оставайтесь на нем:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Далее — набор инструментов:

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

Дождитесь завершения проверок работоспособности (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. Ошибка connection refused на порту 8123 означает, что контейнер все еще запускается или уже завершил работу. docker compose logs clickhouse покажет причину, а docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled сообщит true, если ядро завершило процесс из-за нехватки памяти. Это указывает на недостаточный объем ресурсов сервера, а не на ошибки в конфигурации.

Затем миграция и приложения:

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

Обратите внимание на порт: 5434, а не 5432. Файл compose публикует Postgres на порту 5434, чтобы избежать конфликта с Postgres, уже установленным на хосте. Файлы конфигурации приложения .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 — это место, где следует отслеживать процесс приема данных. В README указано, что веб-приложение работает на http://localhost:5173, API на http://localhost:4100, а прием OTLP на http://localhost:4101.

Перед тем как направлять трафик, убедитесь, что порты действительно прослушиваются:

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

Это важно в дальнейшем. Прокси считывает свой порт из переменной окружения PORT и использует значение 4000 по умолчанию, если PORT не задана. Стек для разработки устанавливает ее автоматически. Юнит systemd, который вы создаете самостоятельно, этого не делает. В результате экспортер, направленный на порт 4101 при прокси, слушающем порт 4000, выдаст ошибку connection refused без каких-либо дополнительных пояснений.

Отправка одной трассировки, воспроизведение одной ошибки, просмотр одного инцидента

Создайте проект в веб-приложении и скопируйте его ключ приема (ingest key). Система приема аутентифицирует каждый запрос по этому ключу, поэтому телеметрия, отправленная без него, никогда не попадет в ClickHouse.

Направьте любой OpenTelemetry SDK на точку приема, используя стандартные переменные окружения:

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'

Точка приема считывает ключ из заголовка x-api-key, а также принимает authorization: bearer YOUR_INGEST_KEY, если ваш экспортер проще настроить таким образом. Она обслуживает три стандартных пути 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, то каждый экспорт будет отправляться на /. Этот маршрут не существует, поэтому данные не доходят, а SDK регистрирует ошибку экспорта, в то время как ваше приложение выглядит работоспособным.

Для Node-сервиса достаточно использовать путь без написания кода (zero code path), чтобы проверить конвейер:

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 при пустом веб-приложении означает несоответствие проекта, поэтому проверьте, к какому проекту относится ключ приема. Статичный счетчик при наличии активности в логах прокси указывает на проблемы с коллектором или записью в ClickHouse, поэтому изучите docker compose logs collector. Отсутствие активности в логах прокси означает, что экспортер не достиг точки приема: неверный порт, неверный путь или отклоненный ключ.

В веб-приложении эти повторяющиеся сбои поступают как один инцидент, а не как отдельная строка на каждый запрос. Superlog создает отпечатки входящих сигналов и группирует совпадающие, что отличает папку «Входящие» с 4 000 идентичных ошибок от страницы с одной записью. Затем агент записывает результаты своего расследования поверх этой группы.

Этап расследования вызывает модель, поэтому для воркера должен быть настроен провайдер модели. Берите имена переменных из файла .env.example внутри каждого каталога приложения того коммита, который вы зафиксировали, а не из внешних руководств, так как они меняются вместе с main. То же самое относится к интеграциям с GitHub и Sentry, которые содержат собственные документы по настройке в docs/github-app-setup.md и docs/sentry-app-setup.md, а полезные нагрузки вебхуков задокументированы в docs/webhooks.md.

Ограничение доступа к системе приема данных и права агента

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, который повторно объявляет ports, так как Compose объединяет списки портов из разных файлов, а не заменяет их. В результате у вас останутся обе привязки, и публичный порт останется открытым.

Система приема данных требует такого же внимания. Ваш ключ для приема данных передается в заголовке, поэтому перед ним необходимо настроить TLS (transport layer security): завершайте TLS в nginx или Caddy перед прокси-сервером либо держите систему приема данных внутри частной сети или туннеля WireGuard. Веб-приложение на порту 5173 — это сервер разработки Vite, и ему не следует быть доступным из Интернета.

Теперь об агенте. Основная идея Superlog заключается в том, что агент исследует проблему и предлагает решение, и ключевое слово здесь — «предлагает». Ограничьтесь режимом «только чтение» для production-среды, пока не убедитесь в его работе на нескольких реальных инцидентах. Предоставьте GitHub App права на чтение и позвольте ему создавать pull requests, которые вы будете проверять. Агент, который читает телеметрию и пишет патчи, полезен. Агент, который может перезапускать ваши сервисы, несет иной уровень риска, и это решение должно быть осознанным, а не принятым по умолчанию. Расходы также заслуживают внимания, так как каждое исследование — это вызов модели: установите бюджет на расходы агента на VPS, прежде чем направлять его на шумную production-систему, и ведите журнал действий агента, чтобы у каждого неожиданного pull request был след для аудита.

Типичные ошибки и их идентификаторы

ERR_PNPM_UNSUPPORTED_ENGINE во время pnpm install означает, что версия Node ниже 20. node -v позволяет проверить это одной командой.
ECONNREFUSED 127.0.0.1:5434 во время миграции означает, что стек compose не запущен, либо DATABASE_URL указывает на неверный порт.
Циклическая перезагрузка ClickHouse обычно вызвана нехваткой памяти. Прочитайте docker compose logs clickhouse, затем проверьте контейнер на наличие OOMKilled со значением true.
Если экспортер сообщает об успехе, но веб-приложение остается пустым, это обычно означает, что данные ушли напрямую в коллектор на порт 4318, минуя маркировку проекта, которую выполняет прокси.
Ошибка Connection refused на порту 4101 в production-инсталляции означает, что прокси переключился на PORT=4000. Явно укажите PORT в файле юнита.
docker compose ps с выводом 0.0.0.0:8123 означает, что привязки к loopback не вступили в силу. Выполните docker compose config и проверьте список активных портов.

Flawless, HyperProbe и место Superlog

Эта категория инструментов молода, и подходы к тому, к каким данным разрешен доступ агенту, различаются. Flawless — это AI SRE-инструмент с открытым исходным кодом для Kubernetes. Он считывает данные из уже развернутого стека Prometheus, Loki и Grafana, не владея конвейером обработки данных. HyperProbe работает иначе: это облачный продукт с закрытым исходным кодом (по состоянию на август 2026 года). Он размещает зонды с доступом только на чтение внутри запущенного процесса для захвата состояния переменных и передает эти данные помощнику через протокол MCP (model context protocol).

Superlog занимает промежуточное положение. Он полностью контролирует конвейер: от приема данных OTLP до хранения в ClickHouse. Агент Superlog размещается на этапе триажа, а не на этапе исправления ошибок. Именно поэтому самостоятельное развертывание Superlog — это инфраструктурное решение, а не просто запуск контейнера, о котором можно забыть. Запуская Superlog, вы запускаете колоночную базу данных, которая требует такого же обслуживания, как и любая другая база данных в вашем ведении.

FAQ

Сколько оперативной памяти требуется для самостоятельного размещения Superlog?

Планируйте 8 ГБ ОЗУ, 4 vCPU и 40 ГБ дискового пространства для одного узла при небольшом объеме входящих данных. Стек состоит из Postgres, ClickHouse, коллектора OpenTelemetry и четырех процессов Node, при этом ClickHouse требует свободного пространства для работы. VPS с 1 ГБ или 2 ГБ памяти недостаточно: pnpm install сам по себе потребляет много ресурсов, а ClickHouse будет принудительно завершен системным OOM-killer при нагрузке. Оценивайте показатели самостоятельно с помощью docker stats --no-stream и free -m, вместо того чтобы полагаться на опубликованные цифры, включая эту.

На какой порт направлять экспортер OTLP?

На прокси приема Superlog, который в README указан как http://localhost:4101. Он обслуживает /v1/traces, /v1/logs и /v1/metrics, а аутентификация происходит по ключу приема вашего проекта, который берется из заголовка x-api-key или authorization: bearer. Порт 4318 принадлежит коллектору OpenTelemetry, работающему «под капотом»; прямая отправка данных туда минует прокси, который отвечает за присвоение идентификатора проекта вашим данным. Если переменная PORT не задана, прокси использует порт 4000, поэтому выполните ss -lntp и проверьте, на каком порту он запущен, прежде чем считать, что это 4101.

Заменяет ли Superlog такие инструменты, как Uptime Kuma или Zabbix?

Нет. Uptime Kuma проверяет, отвечает ли конечная точка извне вашей сети, а Zabbix отслеживает метрики хостов и сервисов на соответствие заданным порогам. Superlog собирает трассировки, логи и метрики, которые генерируют ваши приложения, и группирует повторяющиеся сбои в инциденты. Оставьте внешнюю систему мониторинга доступности, так как проверка извне сообщит о проблеме, даже если сервер, на котором работает ваш конвейер телеметрии, выйдет из строя.

Может ли агент Superlog вносить изменения в мои рабочие системы?

Только с разрешениями, которые вы ему предоставите. Результатом его работы является исследование и предлагаемое изменение, которое проверяет человек. На начальном этапе ограничьте GitHub App правами на чтение и создание pull request, а учетные данные, используемые рабочим процессом, ограничьте доступом только на чтение. Предоставление прав на запись в рабочую среду — это отдельное осознанное решение, так как агент, способный перезапускать сервисы, требует гораздо большего доверия, чем агент, который только читает телеметрию и создает патч для проверки.

Стоит ли фиксировать коммит или отслеживать ветку main?

Фиксируйте коммит. По состоянию на август 2026 года в репозитории нет тегов релизов, поэтому main — единственная доступная динамическая цель, которая обновляется на несколько коммитов в неделю. Зафиксируйте SHA, который вы протестировали, разверните его и изучите diff перед обновлением. git log --oneline <old-sha>..main содержит информацию о проверках, а файлы .env.example для каждого приложения — это первое место, где нужно искать новые обязательные переменные после любого обновления.

#superlog#observability #opentelemetry#clickhouse#ai-sre