Перейти к основному содержанию
ВкратцеСобирайте и визуализируйте системные логи 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 (по умолчанию включена)
1

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

На экземпляре EC2 убедитесь, что служба метаданных доступна:
# Получить токен метаданных (IMDSv2)
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
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 использует эту конечную точку, чтобы автоматически дополнять журналы облачным контекстом.
2

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

Убедитесь, что ваш инстанс EC2 записывает файлы syslog:
# Экземпляры Ubuntu
ls -la /var/log/syslog

# Экземпляры Amazon Linux / RHEL
ls -la /var/log/messages

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

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

Установите дистрибутив OpenTelemetry Collector Contrib на своем экземпляре EC2:
# Скачать последний релиз
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Распаковать и установить
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Проверить установку
otelcol-contrib --version
4

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

Создайте файл конфигурации для OpenTelemetry Collector по пути /etc/otelcol-contrib/config.yaml:
sudo mkdir -p /etc/otelcol-contrib
Выберите конфигурацию в соответствии с вашим дистрибутивом Linux:
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

Замените следующее в конфигурации:
  • 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 экземпляра
5

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

Экспортируйте API-ключ ClickStack в переменную окружения:
export CLICKSTACK_API_KEY="your-api-key-here"
Чтобы это сохранялось после перезагрузки, добавьте это в профиль оболочки:
echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
6

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

Запустите 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.
7

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

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

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

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

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

Скачайте пример файла журнала:
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log
Набор данных включает:
  • Последовательность загрузки системы
  • Активность входа по SSH (успешные и неуспешные попытки)
  • Инцидент безопасности (атака методом перебора и реакция fail2ban)
  • Плановое обслуживание (задания cron, anacron)
  • Перезапуски службы (rsyslog)
  • Сообщения ядра и активность межсетевого экрана
  • Сочетание штатных операций и примечательных событий
2

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

Создайте файл 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:
  # Имитация метаданных EC2 для демонстрации (реальный инстанс EC2 не нужен)
  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.
3

​
Запустите 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
4

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

После запуска collector:
  1. Откройте HyperDX и войдите в свою учетную запись (возможно, сначала потребуется создать ее)
  2. Перейдите в представление поиска и выберите источник Logs
  3. Установите временной диапазон 2025-11-10 00:00:00 - 2025-11-13 00:00:00
  4. Отфильтруйте по source:ec2-demo
  5. Разверните запись в журнале, чтобы просмотреть метаданные 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, мы предоставляем базовые визуализации с облачным контекстом.
1

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

2

​
Импортируйте преднастроенную панель мониторинга

  1. Откройте HyperDX и перейдите в раздел Dashboards
  2. Нажмите Import Dashboard в правом верхнем углу в меню с многоточием
  1. Загрузите файл host-logs-dashboard.json и нажмите Finish Import
3

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

Панель мониторинга будет создана со всеми преднастроенными визуализациями:Вы можете фильтровать визуализации на панели мониторинга по контексту 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.
Последнее изменение 10 июня 2026 г.