Как развернуть Superlog для обработки логов через OTLP
Узнайте, как самостоятельно запустить стек Superlog на собственном VPS через Docker Compose. Разбираем установку Postgres, ClickHouse и настройку сбора OTLP данных.
Что именно устанавливается при self-hosting Superlog
Для self-hosting Superlog необходимо клонировать репозиторий, запустить Postgres, ClickHouse и OpenTelemetry collector через Docker Compose, выполнить одну миграцию базы данных, а затем запустить четыре Node-сервиса из исходного кода. Ваши приложения отправляют трассировки, логи и метрики по протоколу OTLP (OpenTelemetry protocol) на порт приема данных. Superlog создает их цифровые отпечатки, группирует повторяющиеся события в единый инцидент, а стандартный агент сообщества записывает сводку инцидента локально. Установка занимает вторую половину дня. Перед началом работы стоит изучить раздел с требованиями к ресурсам и реальными ограничениями.
Superlog распространяется по лицензии Apache 2.0 и находится по адресу github.com/superloglabs/superlog. По состоянию на 13 октября 2026 года проект имеет около 1.5k звезд, примерно 490 коммитов в ветке main и не имеет ни одного тега релиза. Фиксируйте конкретный коммит самостоятельно, вместо того чтобы запускать то, что оказалось в main в утро клонирования репозитория.
На какие вопросы отвечает Superlog, на которые не отвечают Uptime Kuma и Langfuse
Самохостируемые инструменты мониторинга внешне кажутся взаимозаменяемыми. Это не так, и использование неподходящего инструмента приводит к потере ресурсов сервера без какой-либо пользы.
- Uptime Kuma проверяет ваши эндпоинты извне и отвечает на один вопрос: доступен ли сервис.
- Zabbix отслеживает хосты и сервисы на Ubuntu 24.04, контролируя CPU, память, диск и состояние сервисов на основе заданных вами пороговых значений.
- Langfuse отслеживает вызовы LLM, записывая промпт, модель, токены, задержку и стоимость каждого запроса.
- Superlog берет телеметрию, которую уже генерируют ваши обычные сервисы, и превращает повторяющиеся сбои в инциденты.
Superlog отвечает на другой вопрос: что-то сломалось — что именно и почему. У него нет функций для анализа вызовов LLM, и он не выполняет внешние проверки. Он принимает OTLP из кода вашего приложения и размещает агента на этапе первичной обработки (triage), которую в любом случае первым делом выполняет дежурный инженер.
Различие, важное для бюджета VPS, заключается в хранении данных. Superlog использует колоночное хранилище, так как телеметрия записывается один раз, а затем запрашивается по временным интервалам среди миллионов строк. Именно для этого предназначен ClickHouse, а не Postgres. Postgres остается в стеке для хранения небольших реляционных данных: проектов, пользователей, инцидентов и ключей приема данных.
Что именно запускает docker compose up -d?
Запускаются три контейнера, и ни один из них не является Superlog. Это удивляет пользователей, которые ожидают установки одной командой.
postgres:16, опубликован на порту хоста 5434clickhouse/clickhouse-server:26.1, на порту 8123 для HTTP и 9000 для нативного протоколаotel/opentelemetry-collector-contrib:0.150.1, на порту 4317 для gRPC и 4318 для OTLP поверх HTTP
Приложения Superlog работают на хосте, из исходного кода, запускаемые через pnpm dev. По состоянию на 13 октября 2026 года в репозитории отсутствует compose-файл для production, поэтому для длительной эксплуатации вам потребуются собственные systemd-юниты или Dockerfile для каждого приложения, которые поставляются в составе дерева исходного кода. Приложения api, worker и proxy имеют скрипт start для обертки в юнит. У веб-приложения его нет: это приложение Vite, поэтому вы собираете его с помощью скрипта build и отдаете результат как статические файлы через nginx или Caddy, либо запускаете его скрипт preview, который является vite preview.
Держите в уме путь, который проходит спан, так как каждый сбой ниже — это разрыв на одном из этапов. Ваше приложение отправляет OTLP в прокси приема данных Superlog. Прокси аутентифицирует запрос с помощью вашего ключа ingest key, проставляет на нем идентификатор проекта и пересылает его в коллектор. Коллектор удаляет любые атрибуты 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 спроектирован для машин с большим объемом оперативной памяти, и его настройки по умолчанию рассчитаны на это. Postgres 16 потребляет меньше ресурсов, так как хранит метаданные, а не телеметрию. Коллектор также нетребователен. Четыре процесса Node включают сервер разработки Vite и три процесса tsx watch; измерьте их потребление памяти на вашем сервере.
Дисковое пространство — менее очевидная проблема. 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"Наиболее опасная нагрузка — это всплески: неудачное развертывание, создающее тысячи идентичных ошибок в минуту. Механизм формирования отпечатков (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 отсутствие вывода — ожидаемый результат по состоянию на 13 октября 2026 года. Выберите протестированный коммит и оставайтесь на нем:
git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1eДалее — набор инструментов:
node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -vpackage.json объявляет engines.node как >=20.0.0, а packageManager как pnpm@9.12.0. Несовместимая версия Node не останавливает установку автоматически: принудительная проверка движка зависит от конфигурации, а в 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 postgresClickHouse отвечает 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 запускает turbo run dev, который инициирует скрипт dev для каждого приложения через Turborepo, включая api, web, worker и proxy, объединяя их вывод в одном терминале. Файл Procfile в репозитории перечисляет те же четыре процесса и перенаправляет вывод каждого из них в tmp/logs/. Запускайте его с помощью менеджера Procfile, такого как overmind или foreman, вместо pnpm dev, если хотите, чтобы tail -f tmp/logs/proxy.log был местом, где вы отслеживаете входящие данные. В README веб-приложение указано на порту http://localhost:5173, API — на http://localhost:4100, а прием OTLP — на http://localhost:4101.
Перед тем как направлять трафик, убедитесь, что именно было привязано:
ss -lntp | grep -E '4000|4100|4101|5173'
curl -sS http://127.0.0.1:4101/healthЭто важно в дальнейшем. Прокси считывает свой порт из переменной окружения PORT и использует значение по умолчанию 4000, если PORT не задана; файл apps/proxy/.env.example, который он загружает, также устанавливает PORT=4000, хотя в README прием данных указан на порту 4101 (проверено 13 октября 2026 года). Используйте тот порт, который показывает ss. В примерах ниже используется 4101, поэтому замените его на 4000, если привязка произошла на этот порт. Юнит systemd, который вы создаете самостоятельно, не устанавливает никаких переменных, если вы не добавите PORT в его конфигурацию, поэтому экспортер, направленный на 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), чтобы проверить конвейер:
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 создает отпечатки входящих сигналов и группирует совпадающие, что избавляет вас от необходимости просматривать 4000 идентичных ошибок в почтовом ящике, заменяя их одной записью. Стандартный агент сообщества затем записывает локальную сводку инцидента для этой группы.
Для расследования с использованием моделей требуется настроенный провайдер моделей и совместимый агент; стандартный агент сообщества записывает только локальную сводку. Берите имена переменных из файла .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 направляет трафик контейнеров через таблицу nat, поэтому пакет, предназначенный для опубликованного порта, перенаправляется до того, как попадет в цепочки INPUT и OUTPUT, где находятся правила ufw, и 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. Простое повторное объявление ports в файле переопределения Compose сохраняет обе привязки, если IP-адрес хоста отличается; Compose версии 2.24.4 и выше поддерживает ports: !override для замены списка.
Входящие данные требуют такого же внимания. Ваш ключ для приема данных передается в заголовке, поэтому перед ним необходимо настроить TLS (transport layer security): завершайте TLS в nginx или Caddy перед прокси-сервером либо держите прием данных внутри частной сети или туннеля WireGuard. Веб-приложение на порту 5173 — это сервер разработки Vite, и ему не следует быть доступным из интернета.
Теперь сам агент. Основная идея Superlog заключается в том, что агент анализирует ситуацию и предлагает исправление, и ключевое слово здесь — «предлагает». Оставьте его в режиме «только чтение» для продакшена, пока не убедитесь в его работе на нескольких реальных инцидентах. GitHub App с правами «только чтение» не может отправить ветку с исправлениями или открыть pull request: руководство по настройке требует прав на запись Contents и Pull requests для этого рабочего процесса, а также прав на запись Issues для комментариев. Агент, который считывает телеметрию и создает патч, полезен. Агент, который может перезапускать ваши сервисы, несет иной уровень риска, и это должно быть осознанным решением, а не настройкой по умолчанию. Расходы требуют такого же внимания при настройке исполнителя на базе модели: бюджет на расходы агента на VPS перед тем, как направлять его на нагруженную систему в продакшене, и ведите журнал действий агента, чтобы у неожиданного pull request был след для аудита.
Типичные ошибки и их диагностика
ERR_PNPM_UNSUPPORTED_ENGINEво времяpnpm installозначает несовместимость требований движка. pnpm 9.12.0 проверяет версии Node и pnpm; изучите требуемую и текущую версии в тексте ошибки, затем проверьтеnode -vиpnpm -v.ECONNREFUSED 127.0.0.1:5434во время миграции означает, что стек compose не запущен или вDATABASE_URLуказан неверный порт.- Проверьте перезапуски ClickHouse с помощью
docker compose logs clickhouse, затем проверьте контейнер на наличиеOOMKilledсо значениемtrue. - Если экспортер сообщает об успехе, но веб-приложение остается пустым, это обычно означает, что данные ушли напрямую в коллектор на порт 4318, минуя маркировку проекта, которую выполняет прокси.
- Ошибка Connection refused на порту 4101 обычно означает, что прокси слушает порт 4000 — это порт по умолчанию, к которому возвращается код, и который задается в
.env.example. Явно укажитеPORTв файле юнита или в.envприложения. docker compose psс выводом0.0.0.0:8123означает, что привязки к loopback не активны. Выполнитеdocker compose configи проверьте разрешенные порты.
Flawless, HyperProbe и место Superlog
Эта категория инструментов молода, и подходы к правам доступа агентов в них различаются. Репозиторий Flawless теперь представляет CISRE — платформу AI SRE (инженерия надежности сайта) для Kubernetes и облачной инфраструктуры, распространяемую по лицензии PolyForm Noncommercial. HyperProbe размещает зонды внутри запущенного процесса для захвата состояния переменных и передает эти данные помощнику через MCP (model context protocol); также предусмотрена возможность self-hosting с использованием Docker Compose и лицензионного ключа.
Superlog занимает промежуточное положение. Он контролирует конвейер целиком, от приема данных OTLP до хранения в ClickHouse, и размещает агент на этапе сортировки (triage), а не на этапе исправления. Именно поэтому self-hosting Superlog — это инфраструктурное решение, а не просто контейнер, о котором можно забыть. Запуская Superlog, вы запускаете колоночную базу данных, которая требует такого же обслуживания, как и любая другая база данных в вашем ведении.
FAQ
Сколько оперативной памяти нужно для самостоятельного размещения Superlog?
Планируйте 8 GB оперативной памяти, 4 vCPU и 40 GB дискового пространства для одного узла при небольшом объеме входящих данных. Стек состоит из Postgres, ClickHouse, OpenTelemetry collector и четырех процессов Node, при этом ClickHouse требует резерва памяти. Измеряйте показатели самостоятельно с помощью 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 collector, работающему «под капотом»; прямая отправка данных на него минует прокси, который отвечает за добавление идентификатора вашего проекта к данным. Прокси переключается на порт 4000, если переменная PORT не задана, а его .env.example также устанавливает 4000, поэтому выполните ss -lntp и убедитесь, к какому порту привязался процесс, прежде чем считать, что это 4101.
Заменяет ли Superlog инструменты Uptime Kuma или Zabbix?
Нет. Uptime Kuma отвечает на вопрос, отвечает ли конечная точка извне вашей сети, а Zabbix отслеживает метрики хоста и сервисов на основе заданных вами пороговых значений. Superlog потребляет трассировки, логи и метрики, которые генерируют ваши приложения, и группирует повторяющиеся сбои в инциденты. Оставьте внешний зонд для проверки работоспособности, так как зонд, работающий на другом узле, сообщит о проблеме, если сервер, на котором развернут конвейер телеметрии, выйдет из строя.
Может ли агент Superlog изменять мои производственные системы?
Только в рамках предоставленных вами прав доступа. Стандартный общедоступный раннер записывает локальную сводку инцидентов; другие среды выполнения для расследования зависят от настроенного вами раннера. Ограничьте производственные учетные данные правами на чтение; создание pull requests требует отдельных прав на запись в GitHub для веток и запросов на слияние. Рассматривайте предоставление прав на запись в производственную среду как отдельное осознанное решение, так как агент, способный перезапускать сервисы, требует гораздо более серьезного подхода, чем агент, который только считывает телеметрию и создает патч для проверки.
Стоит ли фиксировать коммит или отслеживать ветку main?
Фиксируйте коммит. По состоянию на 13 октября 2026 года в репозитории не было тегов релизов. Запишите SHA, который вы протестировали, разверните именно его и изучите diff перед обновлением. git log --oneline <old-sha>..main — это и есть список изменений для проверки, а файлы .env.example для каждого приложения — это первое место, где нужно искать новые обязательные переменные после любого обновления версии.