Мониторинг журналов 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.

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

OpenTelemetry Collector отправляет данные в конечную точку OTLP ClickStack, для которой требуется аутентификация.

Откройте HyperDX по URL-адресу ClickStack (например, http://localhost:8080)
Создайте учётную запись или при необходимости войдите в систему
Перейдите в Team Settings → API Keys
Скопируйте ключ API для приёма данных

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

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

Настройка учетных данных 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.

Настройте приёмник 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). При первом запуске он начинает с текущего момента. Исторические журналы по умолчанию не загружаются.

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

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

После запуска коллектора:

Откройте HyperDX по адресу http://localhost:8080 (или по URL вашего ClickStack)
Перейдите в раздел Logs
Подождите 1–2 минуты, пока не появятся журналы (в зависимости от интервала опроса)
Найдите журналы из ваших групп журналов 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.

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

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

Откройте HyperDX по адресу http://localhost:8080 и войдите в систему (при необходимости создайте учетную запись)
Перейдите в раздел Logs
Установите временной диапазон 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)
Выполните поиск по 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, мы предоставляем преднастроенный дашборд с основными визуализациями.

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

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

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

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

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

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

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

Последнее изменение 19 июня 2026 г.

Журналы AWS LambdaМониторинг журналов AWS Lambda в ClickStack с помощью Rotel

​Обзор

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

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

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

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

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

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

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

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

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

​Запустите ClickStack

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

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

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

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

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

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

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

Запустите ClickStack

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

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

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

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

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

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

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

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

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

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

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

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

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

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