Rotel を使って ClickStack で AWS Lambda のログを監視する

Community Maintained

TL;DR

このガイドでは、Rotel Lambda Extension を使用して関数ログ、拡張機能ログ、OpenTelemetry データを収集し、ClickHouse に直接転送することで、ClickStack を使って AWS Lambda 関数を監視する方法を説明します。次のことを行います:

Rotel Lambda Extension レイヤーを Lambda 関数にデプロイする
拡張機能を構成して、ログとトレースを ClickStack にエクスポートする
コスト削減のために、必要に応じて CloudWatch Logs を無効にする

このアプローチにより、CloudWatch Logs を完全にバイパスすることで、Lambda のオブザーバビリティコストを大幅に削減できます。

所要時間: 約 5〜10 分

既存の Lambda 関数との統合

このセクションでは、既存の AWS Lambda 関数を設定し、Rotel Lambda Extension を使用してログとトレースを ClickStack に送信する方法について説明します。

前提条件

ClickStack インスタンスが稼働していること
監視対象となる AWS Lambda 関数が存在すること
適切な権限で設定された AWS CLI があること
レイヤーを追加する権限を持つ Lambda 実行ロールがあること

適切なOTel Lambda Extensionレイヤーを選択する

Rotel Lambda Extensionは、ビルド済みのAWS Lambdaレイヤーとして提供されています。Lambda関数のアーキテクチャに対応するレイヤーARNを選択してください:

アーキテクチャ	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

Lambda関数にRotelレイヤーを追加する

これらの例では、{arch}、{region}、{version} を上記の適切な値で置き換えてください。

オプション1：AWSコンソール

AWS Lambda コンソールを開きます
対象の Lambda 関数に移動します
Layers セクションまでスクロールし、Add a layer をクリックします。
［ARN を指定］を選択します

Rotel レイヤーの ARN を入力してください:

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 Extensionは環境変数を使用して設定します。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ファイルの使用）

より複雑な設定を行う場合は、Lambda関数バンドル内にrotel.envファイルを作成します：

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または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 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（ClickStackのUI）にログインし、ログが正常に取り込まれていることを確認します：

ログ内で以下の主要な属性を探してください:

service.name: 対象の Lambda 関数名
faas.name: AWS Lambda 関数名
faas.invocation_id: 一意の呼び出しID
cloud.provider: "aws"
cloud.platform: "aws_lambda"

CloudWatch Logs を無効化する（コスト最適化）

デフォルトでは、AWS Lambda はすべてのログを CloudWatch Logs に送信しますが、大規模環境では高コストになる場合があります。ログが ClickStack に流れていることを確認できたら、コスト削減のために CloudWatch Logs へのログ送信を無効化してかまいません。

実行ロールから CloudWatch 権限を削除する

AWS マネジメントコンソールを開き、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 の自動計装レイヤーを提供しています：

Language	Layer ARN Pattern
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 Extension レイヤーと計装レイヤーの両方を追加します：

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 でトレースを確認する

関数を呼び出した後、次を確認します：

HyperDX の Traces ビューに移動します
Lambda 関数からの span を含むトレースが表示されていることを確認します
トレースは trace_id と span_id 属性を介してログと相関付けられます

サンプルアプリケーション

Rotel Lambda Extension を利用した Python アプリのサンプルを参照してください：

Python + ClickHouse：OpenTelemetry を手動で計装し、トレースとログを直接 ClickHouse に送信する Python アプリケーション

Rotel コミュニティに参加する

Rotel についてご質問がある場合は、Rotel の Discord サーバーに参加し、フィードバックやご質問をお寄せください。改善に貢献したい場合は、Rotel Lambda Extension をチェックしてみてください。

追加リソース

Rotel Lambda Extension: ソースコードと詳細なドキュメント
Rotel Core: この拡張機能の基盤となる軽量な OTel データプレーン

既存の Lambda 関数との統合​

前提条件​

適切なOTel Lambda Extensionレイヤーを選択する​

Lambda関数にRotelレイヤーを追加する​

オプション1：AWSコンソール​

オプション2：AWS CLI​

オプション3：AWS SAM​

ClickStackへエクスポートするための拡張機能を設定する​

基本設定（環境変数）​

高度な設定（.envファイルの使用）​

AWS Secrets ManagerまたはParameter Storeを使用する​

統合をテストする​

HyperDXでログを検証する​

CloudWatch Logs を無効化する（コスト最適化）​

実行ロールから CloudWatch 権限を削除する​

CloudWatch へのログ出力が無効化されたことを確認する​

OpenTelemetry の自動計装を追加する​

言語ごとの計装レイヤーを選択する​

両方のレイヤーを関数に追加する​

自動計装を設定する​

HyperDX でトレースを確認する​

サンプルアプリケーション​

Rotel コミュニティに参加する​

追加リソース​