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

AWS CloudWatch — это сервис мониторинга ресурсов и приложений AWS. Хотя CloudWatch поддерживает агрегацию журналов, их пересылка в ClickStack позволяет:

• Анализировать журналы вместе с метриками и трейсами на единой платформе
• Запрашивать журналы через SQL-интерфейс ClickHouse
• Снизить затраты за счет архивирования или сокращения срока хранения в CloudWatch

В этом руководстве показано, как пересылать журналы CloudWatch в ClickStack с помощью OpenTelemetry Collector.

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

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

• Запущенный экземпляр ClickStack
• Аккаунт AWS с группами логов CloudWatch
• Учетные данные AWS с соответствующими разрешениями IAM

Получение ключа 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"

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

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

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

# Login to SSO
aws sso login --profile YOUR_PROFILE_NAME

# Export credentials to environment variables
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Verify credentials work
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"

# Verify credentials work
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.

Настройте приёмник 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

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

Создайте файл 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

Проверьте журналы в 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.

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

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: батч-обработка с повторными попытками

Запустите ClickStack

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

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

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

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

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

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

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

После импорта:

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.

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

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

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

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

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

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

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

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

Проверьте, что учетные данные 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, где описаны шаблоны развертывания для продакшн и приведены примеры конфигурации коллектора.