Мониторинг журналов хоста EC2 в ClickStack

ВкратцеСобирайте и визуализируйте системные логи EC2 в ClickStack с помощью OpenTelemetry Collector с автоматическим обогащением метаданными EC2 (ID экземпляра, регион, AZ, тип инстанса). Включает демо-набор данных и преднастроенный дашборд.

Интеграция с существующим экземпляром EC2

В этом разделе описано, как установить OpenTelemetry Collector на экземпляры EC2, чтобы собирать системные журналы и отправлять их в ClickStack с автоматическим обогащением метаданными EC2. Эта распределенная архитектура подходит для production и легко масштабируется на несколько экземпляров.

ClickStack запущен на том же экземпляре EC2?Если ClickStack работает на том же экземпляре EC2, журналы которого вы хотите отслеживать, можно использовать подход all-in-one, аналогичный руководству Generic Host Logs. Подмонтируйте /var/log в контейнер ClickStack и добавьте процессор resourcedetection в свою пользовательскую конфигурацию, чтобы автоматически получать метаданные EC2. В этом руководстве рассматривается более распространенная для production-развертываний распределенная архитектура.

Если вы хотите протестировать интеграцию журналов хоста EC2 перед настройкой production-экземпляра, воспользуйтесь нашей предварительно настроенной конфигурацией и примером данных в разделе “Демо-набор данных”.

Предварительные требования

Запущенный экземпляр ClickStack (может быть развернут в собственной инфраструктуре, в облаке или локально)
Запущенный экземпляр EC2 (Ubuntu, Amazon Linux или другой дистрибутив Linux)
У экземпляра EC2 есть сетевой доступ к конечной точке OTLP ClickStack (порт 4318 для HTTP или 4317 для gRPC)
Есть доступ к службе метаданных экземпляра EC2 (по умолчанию включена)

Убедитесь, что метаданные EC2 доступны

На экземпляре EC2 убедитесь, что служба метаданных доступна:

# Get metadata token (IMDSv2)
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Verify instance metadata
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-type

Вы увидите ID экземпляра, регион и тип инстанса. Если эти команды завершаются ошибкой, проверьте следующее:

Сервис метаданных экземпляра включен
IMDSv2 не блокируется группами безопасности или сетевыми ACL
Вы запускаете эти команды непосредственно из самого экземпляра EC2

Метаданные EC2 доступны по адресу http://169.254.169.254 изнутри экземпляра. Процессор OpenTelemetry resourcedetection использует эту конечную точку, чтобы автоматически дополнять журналы облачным контекстом.

Убедитесь, что файлы syslog присутствуют

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

# Ubuntu instances
ls -la /var/log/syslog

# Amazon Linux / RHEL instances
ls -la /var/log/messages

# View recent entries
tail -20 /var/log/syslog
# or
tail -20 /var/log/messages

Установите OpenTelemetry Collector

Установите дистрибутив OpenTelemetry Collector Contrib на своем экземпляре EC2:

# Download the latest release
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extract and install
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verify installation
otelcol-contrib --version

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

Создайте файл конфигурации для OpenTelemetry Collector по пути /etc/otelcol-contrib/config.yaml:

sudo mkdir -p /etc/otelcol-contrib

Выберите конфигурацию в соответствии с вашим дистрибутивом Linux:

Современные версии Linux (Ubuntu 24.04+)
Старые версии Linux (Amazon Linux 2, RHEL, старые версии Ubuntu)

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
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: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /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: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

Замените следующее в конфигурации:

YOUR_CLICKSTACK_HOST: Имя хоста или IP-адрес, по которому доступен ClickStack
Для локального тестирования можно использовать SSH-туннель (см. раздел «Устранение неполадок»)

Данная конфигурация:

Считывает системные файлы журналов из стандартных путей (/var/log/syslog для Ubuntu, /var/log/messages для Amazon Linux/RHEL)
Разбирает формат syslog для извлечения структурированных полей (временная метка, hostname, unit/service, PID, сообщение)
Автоматически определяет и добавляет метаданные EC2 с помощью процессора resourcedetection
При наличии также может включать теги EC2 (Name, Environment, Team)
Отправляет журналы в ClickStack по OTLP HTTP

Обогащение метаданными EC2Процессор resourcedetection автоматически добавляет следующие атрибуты в каждый лог:

cloud.provider: “aws”
cloud.platform: “aws_ec2”
cloud.region: регион AWS (например, “us-east-1”)
cloud.availability_zone: зона доступности (AZ) (например, “us-east-1a”)
cloud.account.id: ID аккаунта AWS
host.id: ID экземпляра EC2 (например, “i-1234567890abcdef0”)
host.type: тип инстанса (например, “t3.medium”)
host.name: hostname экземпляра

Задайте API-ключ ClickStack

Экспортируйте API-ключ ClickStack в переменную окружения:

export CLICKSTACK_API_KEY="your-api-key-here"

Чтобы это сохранялось после перезагрузки, добавьте это в профиль оболочки:

echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Запустите коллектор

Запустите OpenTelemetry Collector:

CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml

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

Проверка журналов в HyperDX

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

Перейдите в представление Search
В поле source выберите Logs
Отфильтруйте по source:ec2-host-logs
Нажмите на запись в журнале, чтобы развернуть её
Убедитесь, что в атрибутах ресурса отображаются метаданные EC2:
- cloud.provider
- cloud.region
- host.id (ID экземпляра)
- host.type (тип инстанса)
- cloud.availability_zone

Демо-набор данных

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

Скачайте пример набора данных

Скачайте пример файла журнала:

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

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

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

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

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

cat > ec2-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: "ec2-demo"

processors:
  # Simulate EC2 metadata for demo (no real EC2 instance required)
  resource:
    attributes:
      - key: service.name
        value: "ec2-demo"
        action: insert
      - key: cloud.provider
        value: "aws"
        action: insert
      - key: cloud.platform
        value: "aws_ec2"
        action: insert
      - key: cloud.region
        value: "us-east-1"
        action: insert
      - key: cloud.availability_zone
        value: "us-east-1a"
        action: insert
      - key: host.id
        value: "i-0abc123def456789"
        action: insert
      - key: host.type
        value: "t3.medium"
        action: insert
      - key: host.name
        value: "prod-web-01"
        action: insert

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

Для демонстрации мы вручную добавляем метаданные EC2 с помощью процессора resource. В рабочей среде с реальными инстансами EC2 используйте процессор resourcedetection, который автоматически обращается к API метаданных EC2.

Запустите 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)/ec2-host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

Проверьте журналы в HyperDX

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

Откройте HyperDX и войдите в свою учетную запись (возможно, сначала потребуется создать ее)
Перейдите в представление поиска и выберите источник Logs
Установите временной диапазон 2025-11-10 00:00:00 - 2025-11-13 00:00:00
Отфильтруйте по source:ec2-demo
Разверните запись в журнале, чтобы просмотреть метаданные EC2 в атрибутах ресурса

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

Вы должны увидеть журналы со смоделированным контекстом EC2, включая:

ID экземпляра: i-0abc123def456789
Регион: us-east-1
Зона доступности: us-east-1a
Тип инстанса: t3.medium

Панели мониторинга и визуализация

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

Скачать конфигурацию панели мониторинга

Импортируйте преднастроенный дашборд

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

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

Просмотрите панель мониторинга

Панель мониторинга будет создана со всеми преднастроенными визуализациями:Вы можете фильтровать визуализации на панели мониторинга по контексту EC2:

cloud.region:us-east-1 - показать журналы из конкретного региона
host.type:t3.medium - фильтровать по типу инстанса
host.id:i-0abc123def456 - журналы с конкретного инстанса

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

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

Метаданные EC2 не отображаются в журналах

Убедитесь, что сервис метаданных EC2 доступен:

# Получить токен метаданных
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Проверить конечную точку метаданных
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

Если это не помогло, проверьте следующее:

Служба метаданных экземпляра включена
IMDSv2 не блокируется группами безопасности
Вы запускаете коллектор на самом экземпляре EC2

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

# Если запущено как systemd-сервис
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# Если запущено на переднем плане, проверьте stdout

Журналы не отображаются в HyperDX

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

ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog

Проверьте, может ли коллектор читать файлы журналов:

cat /var/log/syslog | head -20

Проверьте сетевую доступность ClickStack:

# Проверка конечной точки OTLP
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# Должен прийти ответ (даже если с ошибкой — это означает, что конечная точка доступна)

Проверьте журналы коллектора на наличие ошибок:

# Если запущен на переднем плане
# Искать сообщения об ошибках в stdout

# Если запущен как сервис systemd
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

Некорректный разбор журналов

Проверьте формат syslog: Для Ubuntu 24.04+:

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

Для Amazon Linux 2 / Ubuntu 20.04:

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

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

Коллектор не запускается как служба systemd

Проверьте статус службы:

sudo systemctl status otelcol-contrib

Просмотр подробных журналов:

sudo journalctl -u otelcol-contrib -n 50

Распространённые проблемы:

API-ключ задан в переменных окружения некорректно
Ошибки синтаксиса в файле конфигурации
Проблемы с правами доступа при чтении файлов журнала

Следующие шаги

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

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

В этом руководстве OpenTelemetry Collector устанавливается непосредственно на экземпляры EC2, что является рекомендуемым вариантом для мониторинга на уровне хоста в продакшн-среде. Для управления коллекторами на множестве экземпляров рассмотрите возможность использования инструментов управления конфигурацией (Ansible, Chef, Puppet) или OpenTelemetry Operator в средах Kubernetes. См. раздел Отправка данных OpenTelemetry с конфигурацией для продакшн-среды.

Возможности

Руководства

Мониторинг журналов хоста EC2 в ClickStack

Интеграция с существующим экземпляром EC2

Предварительные требования

Демо-набор данных

Панели мониторинга и визуализация

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

Метаданные EC2 не отображаются в журналах

Журналы не отображаются в HyperDX

Некорректный разбор журналов

Коллектор не запускается как служба systemd

Следующие шаги

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

​Интеграция с существующим экземпляром EC2

Предварительные требования

​Демо-набор данных

​Панели мониторинга и визуализация

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

​Метаданные EC2 не отображаются в журналах

​Журналы не отображаются в HyperDX

​Некорректный разбор журналов

​Коллектор не запускается как служба systemd

​Следующие шаги

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

Интеграция с существующим экземпляром EC2

Демо-набор данных

Панели мониторинга и визуализация

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

Метаданные EC2 не отображаются в журналах

Журналы не отображаются в HyperDX

Некорректный разбор журналов

Коллектор не запускается как служба systemd

Следующие шаги

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