Мониторинг логов AWS Lambda с ClickStack с использованием Rotel

Community Maintained

TL;DR

В этом руководстве показано, как отслеживать функции AWS Lambda с помощью ClickStack, используя Rotel Lambda Extension для сбора и пересылки логов функций, логов расширения и данных OpenTelemetry напрямую в ClickHouse. Вы узнаете, как:

Развернуть слой Rotel Lambda Extension для ваших функций Lambda
Настроить расширение для экспорта логов и трейсов в ClickStack
При необходимости отключить CloudWatch Logs для снижения затрат

Этот подход может значительно снизить ваши расходы на обсервабилити Lambda за счёт полного отказа от CloudWatch Logs.

Необходимое время: 5–10 минут

Интеграция с существующими функциями Lambda

В этом разделе описывается настройка ваших существующих функций AWS Lambda для отправки логов и трассировок в ClickStack с помощью расширения Rotel Lambda Extension.

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

Запущенный экземпляр ClickStack
Функции AWS Lambda для мониторинга
AWS CLI, настроенный с соответствующими правами доступа
Роль выполнения Lambda с правами на добавление слоёв

Выберите подходящий слой расширения Rotel Lambda Extension

Расширение Rotel Lambda Extension доступно в виде предварительно собранного слоя AWS Lambda. Выберите ARN слоя, который соответствует архитектуре вашей Lambda-функции:

Архитектура	Шаблон ARN	Актуальная версия
x86-64/amd64	`arn:aws:lambda:{region}:418653438961:layer:rotel-extension-amd64-alpha:{version}`
arm64	`arn:aws:lambda:{region}:418653438961:layer:rotel-extension-arm64-alpha:{version}`

Доступные регионы:

us-east-2, us-west-2
eu-central-1, eu-north-1, eu-west-3
ca-central-1
ap-southeast-2, ap-northeast-2
ap-south-1
sa-east-1

Добавьте слой Rotel в вашу Lambda-функцию

В этих примерах замените {arch}, {region} и {version} соответствующими значениями, указанными выше.

Вариант 1: Консоль AWS

Откройте консоль Lambda в AWS
Откройте свою функцию Lambda
Прокрутите страницу до раздела Layers и нажмите Add a layer
Выберите Specify an ARN

Введите ARN слоя Rotel:

arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}-alpha:{version}

Нажмите Add

Вариант 2: AWS CLI

aws lambda update-function-configuration \
  --function-name my-function \
  --layers arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}-alpha:{version}

Вариант 3: AWS SAM

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      # ... other configuration ...
      Layers:
        - arn:aws:lambda:{version}:418653438961:layer:rotel-extension-{arch}-alpha:{version}

Настройте расширение для экспорта данных в ClickStack

Расширение Rotel Lambda настраивается с помощью переменных окружения. Необходимо настроить конечную точку экспортера OTLP так, чтобы она указывала на ваш экземпляр ClickStack. В примерах предполагается, что ваша функция AWS Lambda имеет доступ к экземпляру ClickStack.

Базовая конфигурация (переменные среды)

Добавьте следующие переменные окружения в вашу Lambda-функцию:

# Required: ClickStack OTLP endpoint
ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317

# Optional: Authentication headers
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=<YOUR_INGESTION_API_KEY>"

# Optional: Service name (defaults to Lambda function name)
ROTEL_OTEL_RESOURCE_ATTRIBUTES="service.name=my-lambda-api,service.version=1.0.0"

Расширенная конфигурация (через файл .env)

Для более сложных конфигураций создайте файл rotel.env в пакете Lambda-функции:

rotel.env:

ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=<YOUR_INGESTION_API_KEY>"
ROTEL_OTEL_RESOURCE_ATTRIBUTES="service.name=my-lambda-api,deployment.environment=production"

Затем задайте переменную окружения, указывающую на этот файл:

ROTEL_ENV_FILE=/var/task/rotel.env

Использование AWS Secrets Manager или AWS Systems Manager Parameter Store

Для производственных развертываний храните конфиденциальные данные, такие как API-ключи, в AWS Secrets Manager или Parameter Store:

Пример использования AWS Secrets Manager:

ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=${arn:aws:secretsmanager:us-east-1:123456789012:secret:clickstack-api-key-abc123}"

Пример хранилища параметров AWS (AWS Parameter Store):

ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=${arn:aws:ssm:us-east-1:123456789012:parameter/clickstack-api-key}"

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

Добавьте эти разрешения в роль выполнения Lambda:

Для Secrets Manager:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:BatchGetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:clickstack-api-key-*"
    }
  ]
}

Для Parameter Store:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameters"
      ],
      "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/clickstack-api-key"
    }
  ]
}

Примечание

Вызовы AWS API для получения секретов добавляют 100-150 мс к задержке холодного старта. Секреты извлекаются пакетами (до 10) и только при инициализации, поэтому последующие вызовы не подвержены влиянию.

Тестирование интеграции

Вызовите Lambda-функцию, чтобы убедиться, что логи отправляются в ClickStack:

aws lambda invoke \
  --function-name my-function \
  --payload '{"test": "data"}' \
  response.json

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

aws logs tail /aws/lambda/my-function --follow

Проверьте логи в HyperDX

После настройки войдите в HyperDX (UI ClickStack) и убедитесь, что логи поступают:

Найдите следующие ключевые атрибуты в логах:

service.name: имя вашей функции Lambda
faas.name: имя функции AWS Lambda
faas.invocation_id: Уникальный идентификатор вызова функции
cloud.provider: "aws"
cloud.platform: "aws_lambda"

Отключение CloudWatch Logs (оптимизация затрат)

По умолчанию AWS Lambda отправляет все логи в CloudWatch Logs, что может быть дорого при масштабном использовании. После того как вы проверили, что логи поступают в ClickStack, вы можете отключить логирование в CloudWatch, чтобы снизить затраты.

Удаление прав CloudWatch из роли выполнения

Откройте AWS Console и перейдите в AWS Lambda
Перейдите к своей функции Lambda
Выберите Configuration → Permissions
Нажмите на имя роли выполнения, чтобы открыть консоль IAM
Отредактируйте роль и удалите все действия logs:*:
- Если используется пользовательская политика, отредактируйте её, чтобы удалить logs:CreateLogGroup, logs:CreateLogStream и logs:PutLogEvents
- Если используется управляемая политика AWS AWSLambdaBasicExecutionRole, удалите её из роли
Сохраните роль

Проверка отключения логирования в CloudWatch

Вызовите функцию ещё раз и убедитесь, что:

Новые потоки логов CloudWatch не создаются
Логи продолжают отображаться в ClickStack/HyperDX

# После изменения политики здесь не должно появляться новых потоков логов
aws logs describe-log-streams \
  --log-group-name /aws/lambda/my-function \
  --order-by LastEventTime \
  --descending \
  --max-items 5

Добавление автоинструментирования OpenTelemetry

Расширение Rotel Lambda Extension без дополнительной настройки работает со слоями автоинструментирования OpenTelemetry для сбора распределённых трейсов и метрик в дополнение к логам.

Выберите слой автоинструментирования для вашего языка

AWS предоставляет слои автоинструментирования OpenTelemetry для нескольких языков:

Язык	Шаблон ARN слоя
Node.js	`arn:aws:lambda:{region}:901920570463:layer:aws-otel-nodejs-{arch}-ver-{version}`
Python	`arn:aws:lambda:{region}:901920570463:layer:aws-otel-python-{arch}-ver-{version}`
Java	`arn:aws:lambda:{region}:901920570463:layer:aws-otel-java-agent-{arch}-ver-{version}`

Найдите последние версии в репозитории AWS OpenTelemetry Lambda.

Добавьте оба слоя в вашу функцию

Добавьте оба слоя: слой расширения Rotel и слой автоинструментирования:

aws lambda update-function-configuration \
  --function-name my-function \
  --layers \
    arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}-alpha:{version} \
    arn:aws:lambda:{region}:901920570463:layer:aws-otel-nodejs-{arch}-ver-1-30-2:1

Настройте автоинструментирование

Установите переменную окружения AWS_LAMBDA_EXEC_WRAPPER, чтобы включить автоинструментирование:

Для Node.js:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler

Для Python:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument

Для Java:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler

Проверьте трейсы в HyperDX

После вызова вашей функции:

Перейдите в раздел Traces в HyperDX
Вы должны увидеть трейсы со спанами из вашей функции Lambda
Трейсы будут скоррелированы с логами через атрибуты trace_id и span_id

Примеры приложений

Ознакомьтесь с примером приложения на Python, демонстрирующим Rotel Lambda Extension:

Python + ClickHouse: приложение на Python с ручной инструментировкой OpenTelemetry, которое отправляет трейсы и логи напрямую в ClickHouse

Присоединяйтесь к сообществу Rotel

Если у вас есть вопросы о Rotel, присоединяйтесь к серверу Rotel в Discord и делитесь своими отзывами или вопросами. Ознакомьтесь с Rotel Lambda Extension, чтобы предложить улучшения.

Дополнительные ресурсы

Rotel Lambda Extension: Исходный код и подробная документация
Rotel Core: Легковесная плоскость данных OTel, лежащая в основе расширения

Интеграция с существующими функциями Lambda​

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

Выберите подходящий слой расширения Rotel Lambda Extension​

Добавьте слой Rotel в вашу Lambda-функцию​

Вариант 1: Консоль AWS​

Вариант 2: AWS CLI​

Вариант 3: AWS SAM​

Настройте расширение для экспорта данных в ClickStack​

Базовая конфигурация (переменные среды)​

Расширенная конфигурация (через файл .env)​

Использование AWS Secrets Manager или AWS Systems Manager Parameter Store​

Тестирование интеграции​

Проверьте логи в HyperDX​

Отключение CloudWatch Logs (оптимизация затрат)​

Удаление прав CloudWatch из роли выполнения​

Проверка отключения логирования в CloudWatch​

Добавление автоинструментирования OpenTelemetry​

Выберите слой автоинструментирования для вашего языка​

Добавьте оба слоя в вашу функцию​

Настройте автоинструментирование​

Проверьте трейсы в HyperDX​

Примеры приложений​

Присоединяйтесь к сообществу Rotel​

Дополнительные ресурсы​