Перейти к основному содержанию
КраткоПересылайте журналы AWS CloudWatch в ClickStack с помощью приёмника CloudWatch для OpenTelemetry Collector. Поддерживаются именованные группы логов и автообнаружение. В комплект входят демо-набор данных и преднастроенный дашборд.

Обзор

AWS CloudWatch — это сервис мониторинга ресурсов и приложений AWS. Хотя CloudWatch поддерживает агрегацию журналов, их пересылка в ClickStack позволяет:
  • Анализировать журналы вместе с метриками и трейсами на единой платформе
  • Запрашивать журналы через SQL-интерфейс ClickHouse
  • Снизить затраты за счет архивирования или сокращения срока хранения в CloudWatch
В этом руководстве показано, как пересылать журналы CloudWatch в ClickStack с помощью OpenTelemetry Collector.

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

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

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

  • Запущенный экземпляр ClickStack
  • Аккаунт AWS с группами логов CloudWatch
  • Учетные данные AWS с соответствующими разрешениями IAM
В отличие от интеграций журналов, работающих с файлами (nginx, Redis), для CloudWatch требуется отдельный OpenTelemetry Collector, который опрашивает API CloudWatch. Этот OpenTelemetry Collector не может работать внутри all-in-one-образа ClickStack, так как ему нужны учетные данные AWS и доступ к API.
1

Получение ключа API ClickStack

OpenTelemetry Collector отправляет данные в конечную точку OTLP ClickStack, для которой требуется аутентификация.
  1. Откройте HyperDX по URL-адресу ClickStack (например, http://localhost:8080)
  2. Создайте учётную запись или при необходимости войдите в систему
  3. Перейдите в Team Settings → API Keys
  4. Скопируйте ключ API для приёма данных
Ключ API ClickStack
Сохраните его как переменную окружения:
2

Настройка учетных данных AWS

Экспортируйте учетные данные AWS как переменные окружения. Способ зависит от типа аутентификации:Для пользователей AWS SSO (рекомендуется для большинства организаций):
Замените YOUR_PROFILE_NAME на имя профиля AWS SSO (например, AccountAdministrators-123456789).Для пользователей IAM с долгосрочными учетными данными:
Требуемые разрешения IAM:Для учетной записи AWS, связанной с этими учетными данными, требуется следующая политика IAM для чтения журналов CloudWatch:
Замените YOUR_ACCOUNT_ID на идентификатор вашей учётной записи AWS.
3

Настройте приёмник CloudWatch

Создайте файл otel-collector-config.yaml с конфигурацией приёмника CloudWatch.
Перед редактированием конфигурации выведите список групп логов, существующих в вашем регионе, чтобы выбрать реальные имена и убедиться, что регион указан верно:
Пример вывода:
Используйте имена из этого списка напрямую в блоке groups.named в примере 1 ниже. Для аккаунта выше секция named-groups будет выглядеть так:
Либо, если у нужных вам групп общий префикс (здесь /aws-glue/), используйте пример 2 с prefix: /aws-glue/ вместо перечисления каждой группы отдельно.
Пример 1: Именованные группы логов (рекомендуется)Эта конфигурация собирает журналы из конкретных именованных групп логов:
Пример 2: Автообнаружение групп логов по префиксуЭта конфигурация автоматически обнаруживает и собирает журналы не более чем из 100 групп логов с префиксом /aws/lambda:
Параметры конфигурации:
  • region: регион AWS, в котором находятся ваши группы журналов CloudWatch
  • poll_interval: как часто проверять наличие новых записей в журналах (например, 1m, 5m)
  • max_events_per_request: максимальное количество событий журнала, загружаемых за один запрос
  • groups.autodiscover.limit: максимальное количество групп журналов CloudWatch, которые нужно обнаружить
  • groups.autodiscover.prefix: фильтрация групп журналов CloudWatch по префиксу
  • groups.named: явный список имён групп журналов CloudWatch для сбора
Дополнительные параметры конфигурации см. в документации приёмника CloudWatch.Замените следующее:
  • ${CLICKSTACK_API_KEY} → использует переменную окружения, которую вы задали ранее
  • http://localhost:4318 → ваша конечная точка ClickStack (если ClickStack запущен удалённо, используйте его хост)
  • us-east-1 → ваш регион AWS
  • Имена/префиксы групп журналов → ваши реальные группы журналов CloudWatch
Приёмник CloudWatch загружает журналы только из недавних временных окон (в зависимости от poll_interval). При первом запуске он начинает с текущего момента. Исторические журналы по умолчанию не загружаются.
4

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

Создайте файл docker-compose.yaml:
Затем запустите коллектор:
Просмотрите журналы collector:
5

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

После запуска коллектора:
  1. Откройте HyperDX по адресу http://localhost:8080 (или по URL вашего ClickStack)
  2. Перейдите в раздел Logs
  3. Подождите 1–2 минуты, пока не появятся журналы (в зависимости от интервала опроса)
  4. Найдите журналы из ваших групп журналов CloudWatch
Раздел поиска журналов
Обратите внимание на следующие ключевые атрибуты в журналах:
  • ResourceAttributes['aws.region']: ваш регион AWS (например, “us-east-1”)
  • ResourceAttributes['cloudwatch.log.group.name']: имя группы журналов CloudWatch
  • ResourceAttributes['cloudwatch.log.stream']: имя потока журналов
  • Body: фактическое содержимое сообщения журнала
Значения столбца журнала ошибок

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

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

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

Набор данных включает журналы CloudWatch за 24 часа из нескольких сервисов:
  • Lambda functions: обработка платежей, управление заказами, аутентификация
  • ECS services: API-шлюз с ограничением скорости и тайм-аутами
  • Background jobs: батч-обработка с повторными попытками
2

Запустите ClickStack

Если ClickStack у вас еще не запущен:
Подождите немного, пока ClickStack полностью запустится.
3

Импортируйте демо-набор данных

Это импортирует журналы напрямую в таблицу журналов ClickStack.
4

Проверьте демо-данные

После импорта:
  1. Откройте HyperDX по адресу http://localhost:8080 и войдите в систему (при необходимости создайте учетную запись)
  2. Перейдите в раздел Logs
  3. Установите временной диапазон 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)
  4. Выполните поиск по cloudwatch-demo или отфильтруйте по LogAttributes['source'] = 'cloudwatch-demo'
Вы должны увидеть журналы из нескольких групп логов CloudWatch.
Демонстрационный экран поиска
Отображение часового поясаHyperDX отображает временные метки в локальном часовом поясе вашего браузера. Демо-данные охватывают период 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC). Установите временной диапазон 2025-12-06 00:00:00 - 2025-12-09 00:00:00, чтобы гарантированно увидеть демонстрационные журналы независимо от вашего местоположения. Когда журналы появятся, можно сузить диапазон до 24 часов для более наглядной визуализации.

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

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

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

.
2

Импортируйте панель мониторинга

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

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

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

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

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

Проверьте, что учетные данные AWS настроены:
Если это не помогло, ваши учетные данные недействительны или срок их действия истек. Проверьте разрешения IAM: Убедитесь, что у ваших учетных данных AWS есть необходимые разрешения logs:DescribeLogGroups и logs:FilterLogEvents. Проверьте журналы коллектора на наличие ошибок:
Распространённые ошибки:
  • The security token included in the request is invalid: Учетные данные недействительны или срок их действия истёк. Для временных учетных данных (SSO) убедитесь, что задана переменная AWS_SESSION_TOKEN.
  • operation error CloudWatch Logs: FilterLogEvents, AccessDeniedException: Недостаточно разрешений IAM
  • failed to refresh cached credentials, no EC2 IMDS role found: Не заданы переменные среды с учетными данными AWS
  • connection refused: Конечная точка ClickStack недоступна
Убедитесь, что группы логов CloudWatch существуют и содержат недавние записи:

Видны только старые журналы или отсутствуют недавние журналы

По умолчанию приёмник CloudWatch начинает с “текущего момента”: При первом запуске коллектор создаёт контрольную точку на текущий момент времени и получает только журналы, появившиеся после него. Исторические журналы не загружаются. Чтобы собрать недавние исторические журналы: Остановите и удалите контрольную точку коллектора, затем перезапустите его:
Приёмник создаст новую контрольную точку и начнёт получать журналы с текущего момента.

Недействительный токен безопасности / срок действия учетных данных истёк

Если вы используете временные учетные данные (AWS SSO, assumed role), через некоторое время срок их действия истекает. Повторно экспортируйте актуальные учетные данные:

Высокая задержка или отсутствие свежих журналов

Уменьшите интервал опроса: По умолчанию poll_interval составляет 1 минуту. Чтобы журналы поступали почти в реальном времени, уменьшите его:
Примечание: При меньшем интервале опроса число вызовов AWS API увеличивается, что может привести к росту расходов на API CloudWatch.

Коллектор использует слишком много памяти

Уменьшите размер батча или увеличьте тайм-аут:
Ограничьте автообнаружение:

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

  • Настройте оповещения для критически важных событий (сбоев соединения, всплесков ошибок)
  • Снизьте затраты на CloudWatch, скорректировав сроки хранения или архивируя данные в S3, теперь, когда журналы уже есть в ClickStack
  • Отфильтруйте шумные группы логов, удалив их из конфигурации коллектора, чтобы сократить объём ингестии

Переход к продакшн-развертыванию

В этом руководстве показано, как запускать OpenTelemetry Collector локально с помощью Docker Compose для тестирования. Для развертываний в продакшн запускайте коллектор в инфраструктуре с доступом к AWS (EC2 с ролями IAM, EKS с IRSA или ECS с ролями задач), чтобы не управлять ключами доступа вручную. Развертывайте коллекторы в том же регионе AWS, что и ваши группы журналов CloudWatch, чтобы снизить задержки и затраты. См. Приём данных через OpenTelemetry, где описаны шаблоны развертывания для продакшн и приведены примеры конфигурации коллектора.