Мониторинг журналов хоста с помощью ClickStack

Кратко

В этом руководстве показано, как отслеживать журналы хост-системы с помощью ClickStack, настроив OTel collector для сбора логов от systemd, ядра, SSH, cron и других системных сервисов. Вы узнаете, как:

• Настроить OTel collector для чтения файлов системных логов
• Развернуть ClickStack с вашей собственной конфигурацией
• Использовать готовую панель мониторинга для визуализации данных по журналам хоста (ошибки, предупреждения, активность сервисов)

Демонстрационный набор данных с примерами логов доступен, если вы хотите протестировать интеграцию до настройки боевых хостов.

Требуемое время: 5–10 минут

Интеграция с существующими хостами

В этом разделе описывается настройка ваших существующих хостов для отправки системных логов в ClickStack путем изменения конфигурации ClickStack OTel collector так, чтобы он считывал все файлы системных логов (syslog, auth, kernel, daemon и журналы приложений).

Если вы хотите протестировать интеграцию с журналами хоста до настройки собственной среды, вы можете воспользоваться нашей предварительно настроенной конфигурацией и примеровыми данными в разделе "Demo dataset".

Требования

• Запущенный экземпляр ClickStack
• Система, на которой имеются файлы syslog
• Доступ к изменению файлов конфигурации ClickStack

Проверьте наличие файлов syslog

Сначала убедитесь, что ваша система записывает файлы syslog:

# Проверка наличия файлов syslog (Linux)
ls -la /var/log/syslog /var/log/messages

# Или на macOS
ls -la /var/log/system.log

# Просмотр последних записей
tail -20 /var/log/syslog

Стандартные расположения syslog:

• Ubuntu/Debian: /var/log/syslog
• RHEL/CentOS/Fedora: /var/log/messages
• macOS: /var/log/system.log

Создайте пользовательскую конфигурацию OTel collector

ClickStack позволяет расширить базовую конфигурацию OpenTelemetry Collector путём монтирования пользовательского конфигурационного файла и задания переменной окружения.

Создайте файл host-logs-monitoring.yaml с конфигурацией для вашей системы:

Современный Linux (Ubuntu 24.04+)

receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

service:
  pipelines:
    logs/host:
      receivers: [filelog/syslog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Устаревшие версии Linux (Ubuntu 20.04, RHEL, CentOS)

receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/messages
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

service:
  pipelines:
    logs/host:
      receivers: [filelog/syslog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

macOS

receivers:
  filelog/syslog:
    include:
      - /var/log/system.log
      - /host/private/var/log/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

service:
  pipelines:
    logs/host:
      receivers: [filelog/syslog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Все конфигурации:

• Чтение файлов syslog из стандартных путей
• Разобрать сообщения в формате syslog, чтобы извлечь структурированные поля (timestamp, hostname, unit/service, PID, message)
• Сохраняйте исходные временные метки логов
• Добавьте атрибут source: host-logs для фильтрации данных в HyperDX
• Направьте логи в экспортёр ClickHouse через отдельный pipeline

Примечание

• В пользовательской конфигурации вы задаёте только новые receivers и pipelines
• Процессоры (memory_limiter, transform, batch) и экспортёры (clickhouse) уже определены в базовой конфигурации ClickStack — вы просто ссылаетесь на них по имени
• Regex-парсер извлекает имена юнитов systemd, PID'ы и другие метаданные из сообщений в формате syslog
• Эта конфигурация использует start_at: end, чтобы избежать повторного приёма логов при перезапусках коллектора. Для тестирования измените на start_at: beginning, чтобы сразу увидеть предыдущие логи.

Настройте ClickStack для загрузки пользовательской конфигурации

Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании ClickStack, необходимо:

1. Подмонтируйте пользовательский конфигурационный файл в /etc/otelcol-contrib/custom.config.yaml
2. Установите переменную окружения CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
3. Примонтируйте каталог с журналами syslog, чтобы коллектор мог их считывать

Вариант 1: Docker Compose

Обновите конфигурацию развертывания ClickStack:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log:/var/log:ro
      # ... other volumes ...

Вариант 2: Docker Run (образ «всё в одном»)

Если вы используете универсальный образ с docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log:/var/log:ro \
  clickhouse/clickstack-all-in-one:latest

Примечание

Убедитесь, что коллектор ClickStack имеет необходимые права для чтения файлов syslog. В production-среде используйте монтирование только для чтения (:ro) и следуйте принципу минимальных привилегий.

Проверка логов в HyperDX

После настройки войдите в HyperDX и убедитесь, что журналы поступают:

1. Перейдите на страницу поиска
2. В качестве источника выберите Logs
3. Отфильтруйте логи по source:host-logs, чтобы увидеть логи конкретного хоста
4. Вы должны увидеть структурированные записи логов с такими полями, как unit, hostname, pid, message и т.д.

Демонстрационный набор данных

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

Загрузите пример набора данных

Загрузите пример файла логов:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log

Набор данных включает:

• Последовательность загрузки системы
• Активность входа по SSH (успешные и неуспешные попытки)
• Инцидент безопасности (атака методом перебора с реакцией fail2ban)
• Плановое обслуживание (cron-задания, anacron)
• Перезапуски сервисов (rsyslog)
• Сообщения ядра и активность межсетевого экрана
• Сочетание нормальной работы и заметных событий

Создайте тестовую конфигурацию коллектора

Создайте файл с именем host-logs-demo.yaml со следующей конфигурацией:

cat > host-logs-demo.yaml << 'EOF'
receivers:
  filelog/journal:
    include:
      - /tmp/host-demo/journal.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%Y-%m-%dT%H:%M:%S%z'
      
      - type: add
        field: attributes.source
        value: "host-demo"
      
      - type: add
        field: resource["service.name"]
        value: "host-demo"

service:
  pipelines:
    logs/host-demo:
      receivers: [filelog/journal]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Запустите ClickStack с демонстрационной конфигурацией

Запустите ClickStack с демонстрационными логами и конфигурацией:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Примечание

При этом файл логов монтируется непосредственно в контейнер. Это сделано для целей тестирования со статическими демонстрационными данными.

Проверьте логи в HyperDX

После запуска ClickStack:

1. Откройте HyperDX и войдите в свою учетную запись (возможно, вам сначала потребуется создать учетную запись)
2. Перейдите в раздел Search и установите источник Logs
3. Установите диапазон времени на 2025-11-10 00:00:00 - 2025-11-13 00:00:00

Отображение часового пояса

HyperDX отображает временные метки в локальном часовом поясе вашего браузера. Демонстрационные данные охватывают период 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC). Широкий временной диапазон гарантирует, что вы увидите демонстрационные логи независимо от вашего местоположения. После того как вы увидите логи, вы можете сузить диапазон до 24 часов для более наглядной визуализации.

Дашборды и визуализация

Чтобы вы могли начать мониторинг логов хоста с помощью ClickStack, мы предоставляем основные визуализации для системных логов.

Скачать конфигурацию дашборда

Импорт готового дашборда

1. Откройте HyperDX и перейдите в раздел Dashboards
2. Нажмите Import Dashboard в правом верхнем углу под значком с многоточием

3. Загрузите файл host-logs-dashboard.json и нажмите Finish Import

Просмотр дашборда

Дашборд будет создан со всеми преднастроенными визуализациями:

Ключевые визуализации включают:

• Объём логов во времени по уровням важности
• Топ юнитов systemd, генерирующих логи
• Активность SSH-подключений (успешные vs неудачные)
• Активность межсетевого экрана (заблокировано vs разрешено)
• События безопасности (неудачные входы, блокировки, баны)
• Активность перезапуска сервисов

Примечание

Для демонстрационного датасета установите диапазон времени 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) (скорректируйте в соответствии с вашим часовым поясом). По умолчанию у импортированного дашборда диапазон времени не задан.

Устранение неполадок

Пользовательская конфигурация не загружается

Убедитесь, что задана переменная среды:

docker exec <имя-контейнера> printenv CUSTOM_OTELCOL_CONFIG_FILE

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

docker exec <имя-контейнера> cat /etc/otelcol-contrib/custom.config.yaml | head -10

В HyperDX не отображаются логи

Проверьте, что файлы syslog существуют и в них ведётся запись:

# Проверить наличие syslog
ls -la /var/log/syslog /var/log/messages

# Убедиться, что логи записываются
tail -f /var/log/syslog

Убедитесь, что коллектор может читать логи:

docker exec <container> cat /var/log/syslog | head -20

Убедитесь, что в итоговой конфигурации указан ваш приёмник filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Проверьте наличие ошибок в логах коллектора:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i "filelog\|syslog"

Если используете демонстрационный набор данных, убедитесь, что файл журнала доступен:

docker exec <container> cat /tmp/host-demo/journal.log | wc -l

Логи разбираются некорректно

Убедитесь, что формат сообщений syslog соответствует выбранной конфигурации:

Для современных версий Linux (Ubuntu 24.04+):

# Должен отображать формат ISO8601: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

Для старых версий Linux или macOS:

# Должен отображаться традиционный формат: Nov 17 14:16:16
tail -5 /var/log/syslog
# или
tail -5 /var/log/system.log

Если ваш формат отличается, выберите соответствующую вкладку конфигурации в разделе Создание пользовательской конфигурации OTel collector.

Дальнейшие шаги

После настройки мониторинга логов хоста:

• Настройте оповещения для критических системных событий (сбоев сервисов, ошибок аутентификации, предупреждений о диске)
• Фильтруйте по отдельным unit-ам для мониторинга конкретных сервисов
• Коррелируйте логи хоста с логами приложений для комплексного устранения неполадок
• Создавайте пользовательские дашборды для мониторинга безопасности (попытки SSH-доступа, использование sudo, блокировки межсетевым экраном)

Переход в продакшн

В этом руководстве используется встроенный в ClickStack OTel collector для быстрой начальной настройки. Для продакшн-сред мы рекомендуем развернуть собственный OTel collector и отправлять данные на OTLP-эндпоинт ClickStack. См. раздел Отправка данных OpenTelemetry для конфигурации продакшн-среды.