Мониторинг журналов AWS CloudWatch в ClickStack

Мониторинг журналов AWS CloudWatch в ClickStack

Кратко

Пересылайте журналы 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 для приёма данных

   Сохраните его как переменную окружения:

   export CLICKSTACK_API_KEY="your-api-key-here"
   
2. ​

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

   Экспортируйте учетные данные AWS как переменные окружения. Способ зависит от типа аутентификации:

   Для пользователей AWS SSO (рекомендуется для большинства организаций):

   # Войти в SSO
   aws sso login --profile YOUR_PROFILE_NAME
   
   # Экспортировать учётные данные в переменные окружения
   eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)
   
   # Проверить работоспособность учётных данных
   aws sts get-caller-identity
   

   Замените YOUR_PROFILE_NAME на имя профиля AWS SSO (например, AccountAdministrators-123456789).

   Для пользователей IAM с долгосрочными учетными данными:

   export AWS_ACCESS_KEY_ID="your-access-key-id"
   export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
   export AWS_REGION="us-east-1"
   
   # Проверьте работоспособность учётных данных
   aws sts get-caller-identity
   

   Требуемые разрешения IAM:

   Для учетной записи AWS, связанной с этими учетными данными, требуется следующая политика IAM для чтения журналов CloudWatch:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "CloudWatchLogsRead",
         "Effect": "Allow",
         "Action": [
           "logs:DescribeLogGroups",
           "logs:FilterLogEvents"
         ],
         "Resource": "arn:aws:logs:*:YOUR_ACCOUNT_ID:log-group:*"
       }
     ]
   }
   

   Замените YOUR_ACCOUNT_ID на идентификатор вашей учётной записи AWS.

3. ​

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

   Создайте файл otel-collector-config.yaml с конфигурацией приёмника CloudWatch.

   Найдите группы логов, доступные в вашем аккаунте

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

   aws logs describe-log-groups --region us-east-1 \
     --query 'logGroups[].logGroupName' --output table
   

   Пример вывода:

   -------------------------------
   |      DescribeLogGroups      |
   +-----------------------------+
   |  /aws-glue/jobs/error       |
   |  /aws-glue/jobs/logs-v2     |
   |  /aws-glue/jobs/output      |
   |  /aws-glue/sessions/error   |
   |  /aws-glue/sessions/output  |
   +-----------------------------+
   

   Используйте имена из этого списка напрямую в блоке groups.named в примере 1 ниже. Для аккаунта выше секция named-groups будет выглядеть так:

   groups:
     named:
       /aws-glue/jobs/error:
       /aws-glue/jobs/logs-v2:
       /aws-glue/jobs/output:
       /aws-glue/sessions/error:
       /aws-glue/sessions/output:
   

   Либо, если у нужных вам групп общий префикс (здесь /aws-glue/), используйте пример 2 с prefix: /aws-glue/ вместо перечисления каждой группы отдельно.

   Пример 1: Именованные группы логов (рекомендуется)

   Эта конфигурация собирает журналы из конкретных именованных групп логов:

   receivers:
     awscloudwatch:
       region: us-east-1
       logs:
         poll_interval: 1m
         max_events_per_request: 100
         groups:
           named:
             /aws/lambda/my-function:
             /aws/ecs/my-service:
             /aws/eks/my-cluster/cluster:
   
   processors:
     batch:
       timeout: 10s
   
   exporters:
     otlphttp:
       endpoint: http://localhost:4318
       headers:
         authorization: ${CLICKSTACK_API_KEY}
   
   service:
     pipelines:
       logs:
         receivers: [awscloudwatch]
         processors: [batch]
         exporters: [otlphttp]
   

   Пример 2: Автообнаружение групп логов по префиксу

   Эта конфигурация автоматически обнаруживает и собирает журналы не более чем из 100 групп логов с префиксом /aws/lambda:

   receivers:
     awscloudwatch:
       region: us-east-1
       logs:
         poll_interval: 1m
         max_events_per_request: 100
         groups:
           autodiscover:
             limit: 100
             prefix: /aws/lambda
   
   processors:
     batch:
       timeout: 10s
   
   exporters:
     otlphttp:
       endpoint: http://localhost:4318
       headers:
         authorization: ${CLICKSTACK_API_KEY}
   
   service:
     pipelines:
       logs:
         receivers: [awscloudwatch]
         processors: [batch]
         exporters: [otlphttp]
   

   Параметры конфигурации:

   • 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:

   services:
     otel-collector:
       image: otel/opentelemetry-collector-contrib:latest
       command: ["--config=/etc/otel-config.yaml"]
       volumes:
         - ./otel-collector-config.yaml:/etc/otel-config.yaml
       environment:
         - AWS_ACCESS_KEY_ID
         - AWS_SECRET_ACCESS_KEY
         - AWS_SESSION_TOKEN
         - AWS_REGION
         - CLICKSTACK_API_KEY
       restart: unless-stopped
       extra_hosts:
         - "host.docker.internal:host-gateway"
   

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

   docker compose up -d
   

   Просмотрите журналы collector:

   docker compose logs -f otel-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. ​

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

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/aws/cloudwatch/cloudwatch-logs.jsonl
   

   Набор данных включает журналы CloudWatch за 24 часа из нескольких сервисов:

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

   Запустите ClickStack

   Если ClickStack у вас еще не запущен:

   docker run -d --name clickstack \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

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

3. ​

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

   docker exec -i clickstack clickhouse-client --query="
     INSERT INTO default.otel_logs FORMAT JSONEachRow
   " < cloudwatch-logs.jsonl
   

   Это импортирует журналы напрямую в таблицу журналов 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 и перейдите в раздел Dashboards
   2. Нажмите Import Dashboard в правом верхнем углу в меню с многоточием

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

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

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

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

​

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

​

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

Проверьте, что учетные данные AWS настроены:

aws sts get-caller-identity

Если это не помогло, ваши учетные данные недействительны или срок их действия истек.

Проверьте разрешения IAM: Убедитесь, что у ваших учетных данных AWS есть необходимые разрешения logs:DescribeLogGroups и logs:FilterLogEvents.

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

# При прямом использовании Docker журналы выводятся в stdout
# При использовании Docker Compose:
docker compose logs otel-collector

Распространённые ошибки:

• 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 существуют и содержат недавние записи:

# Список групп логов
aws logs describe-log-groups --region us-east-1

# Проверка наличия свежих записей в конкретной группе логов (за последний час)
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --region us-east-1 \
  --start-time $(date -u -v-1H +%s)000 \
  --max-items 5

​

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

По умолчанию приёмник CloudWatch начинает с “текущего момента”:

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

Чтобы собрать недавние исторические журналы:

Остановите и удалите контрольную точку коллектора, затем перезапустите его:

# Остановить collector
docker stop <container-id>

# Перезапустить заново (контрольные точки хранятся в контейнере, поэтому его удаление сбрасывает их)
docker run --rm ...

Приёмник создаст новую контрольную точку и начнёт получать журналы с текущего момента.

​

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

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

Повторно экспортируйте актуальные учетные данные:

# Для пользователей SSO:
aws sso login --profile YOUR_PROFILE_NAME
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Для пользователей IAM:
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# Перезапустите коллектор
docker restart <container-id>

​

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

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

logs:
  poll_interval: 30s  # Опрос каждые 30 секунд

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

​

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

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

processors:
  batch:
    timeout: 5s
    send_batch_size: 100

Ограничьте автообнаружение:

groups:
  autodiscover:
    limit: 50  # Уменьшить со 100 до 50

​

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

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

​

Развертывание в продакшене

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

См. Приём данных через OpenTelemetry, где приведены варианты продакшен-развертывания и примеры конфигурации коллектора.