使用 Rotel 和 ClickStack 监控 AWS Lambda 日志

由社区维护

与现有 Lambda 函数集成

本节介绍如何配置现有的 AWS Lambda 函数，通过 Rotel Lambda Extension 将日志和链路追踪发送到 ClickStack。

前置条件

正在运行的 ClickStack 实例
需要监控的 AWS Lambda 函数
已配置 AWS CLI，并具有相应权限
具有添加 layer 权限的 Lambda 执行角色

选择合适的 Rotel Lambda Extension layer

选择与 Lambda runtime 架构匹配的 Lambda layer。{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 layer 添加到 Lambda 函数

在这些示例中，请将 {arch}、{region} 和 {version} 替换为上方对应的值。

选项 1：AWS Console

打开 AWS Lambda 控制台
导航到你的 Lambda 函数
滚动到 Layers 部分，然后点击 Add a layer
选择 Specify an ARN

输入 Rotel layer 的 ARN：

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

点击 Add

选项 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"
    }
  ]
}

测试集成

调用你的 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 日志 (成本优化)

默认情况下，AWS Lambda 会将所有日志发送到 CloudWatch 日志，这在大规模场景下成本可能较高。确认日志已流向 ClickStack 后，您可以禁用 CloudWatch 日志记录以降低成本。

从执行角色中移除 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 自动插桩 layer 无缝协同工作，除日志外，还可收集分布式链路追踪和指标。

选择对应语言的插桩 layer

AWS 为多种语言提供了 OpenTelemetry 自动插桩 layer：

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 repository。

将两个 layer 都添加到函数中

同时添加 Rotel extension layer 和插桩 layer：

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 环境变量以启用自动插桩：

对于 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 函数 spans 的链路追踪
链路追踪会通过 trace_id 和 span_id 属性与日志关联起来

示例应用

查看演示 Rotel Lambda Extension 的 Python 示例应用：

Python + ClickHouse：采用手动 OpenTelemetry 埋点的 Python 应用，直接将链路追踪和日志发送到 ClickHouse

加入 Rotel 社区

如果你对 Rotel 有任何疑问，请加入 Rotel Discord 服务器，分享你的反馈或提出问题。也欢迎查看 Rotel Lambda Extension 并贡献改进意见。

其他资源

Rotel Lambda Extension：源代码及详细文档
Rotel Core：为该扩展提供支持的轻量级 OTel 数据平面