Rotel を使用した ClickStack による AWS Lambda ログの監視

コミュニティ管理

既存のLambda関数とのインテグレーション

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

前提条件

稼働中の ClickStack インスタンス
監視対象の AWS Lambda 関数
適切な権限で設定済みの AWS CLI
レイヤーを追加する権限を持つ Lambda 実行ロール

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

Lambda のランタイムアーキテクチャに合った Lambda レイヤーを選択します。{version} フィールドは、デプロイ先の AWS リージョンによって異なります。お使いのリージョンに対応する最新のバージョン番号については、releases ページを確認してください。

アーキテクチャ	ARN
x86-64/amd64	`arn:aws:lambda:{region}:418653438961:layer:rotel-extension-amd64:{version}`
arm64	`arn:aws:lambda:{region}:418653438961:layer:rotel-extension-arm64:{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} を上記の該当する値に置き換えてください。

Option 1: AWS コンソール

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

Rotel レイヤーの ARN を入力します。

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

Add をクリックします

Option 2: AWS CLI

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

オプション 3: AWS SAM

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      # ... other configuration ...
      Layers:
        - arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{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"
    }
  ]
}

インテグレーションをテストする

ログが ClickStack に送信されていることを確認するため、Lambda 関数を呼び出します。

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 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 の自動インストルメンテーションレイヤーが提供されています。

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 拡張レイヤーとインストルメンテーションレイヤーの両方を追加します。

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

自動インストルメンテーションを設定する

自動インストルメンテーションを有効にするには、環境変数 AWS_LAMBDA_EXEC_WRAPPER を設定します。

For Node.js:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler

For Python:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument

For Java:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler

HyperDX でトレースを確認する

関数を実行した後:

HyperDX の Traces ビューを開きます
Lambda 関数からの span を含むトレースが表示されるはずです
トレースは trace_id と span_id attribute を介してログと相関付けられます

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

Rotel Lambda Extension を紹介するサンプルの Python アプリを確認してください。

Python + ClickHouse: 手動で OpenTelemetry をインストルメントした Python アプリケーション。トレースとログを ClickHouse に直接送信します

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

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

参考資料

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