Rotel을 사용한 ClickStack의 AWS Lambda 로그 모니터링

요약이 가이드에서는 Rotel Lambda Extension을 사용해 함수 로그, 확장 로그, OpenTelemetry 데이터를 직접 ClickHouse로 수집하고 전송하여 AWS Lambda 함수를 ClickStack으로 모니터링하는 방법을 설명합니다. 다음 내용을 알아봅니다:

Lambda 함수에 Rotel Lambda Extension 레이어 배포
로그와 트레이스를 ClickStack으로 내보내도록 확장 기능 구성
비용 절감을 위해 필요에 따라 CloudWatch Logs 비활성화

이 방식은 CloudWatch Logs를 완전히 우회하므로 Lambda 관측성 비용을 크게 줄일 수 있습니다.소요 시간: 5-10분

기존 Lambda 함수와의 통합

이 섹션에서는 Rotel Lambda Extension을 사용해 기존 AWS Lambda 함수에서 로그와 트레이스를 ClickStack으로 전송하도록 구성하는 방법을 설명합니다.

사전 요구 사항

실행 중인 ClickStack 인스턴스
모니터링할 AWS Lambda 함수
적절한 권한으로 구성된 AWS CLI
레이어를 추가할 수 있는 권한이 있는 Lambda 실행 역할

적절한 Rotel Lambda Extension layer 선택하기

Lambda 런타임 아키텍처에 맞는 Lambda layer를 선택하십시오. {version} 필드는 배포 대상 AWS 리전에 따라 달라집니다. 해당 리전에 맞는 최신 버전 번호는 releases 페이지에서 확인하십시오.

Architecture	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-, us-west-
eu-central-1, eu-north-1, eu-west-
ca-central-1
ap-southeast-, ap-northeast-
ap-south-1
sa-east-1

Lambda 함수에 Rotel 레이어 추가

이 예시에서는 {arch}, {region}, {version}을 위의 적절한 값으로 바꾸십시오.

옵션 1: AWS Console

AWS Lambda 콘솔을 엽니다
Lambda 함수로 이동합니다
Layers 섹션으로 스크롤한 다음 Add a layer를 클릭합니다
Specify an ARN을 선택합니다

Rotel 레이어 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 exporter endpoint가 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 Key와 같은 민감한 값을 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~150ms가 추가됩니다. 시크릿은 한 번에 최대 10개씩 묶음으로 초기화 시에만 가져오므로, 이후 호출에는 영향을 주지 않습니다.

통합 테스트

ClickStack으로 로그가 전송되는지 확인하려면 람다 함수를 호출하세요:

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

Lambda logs에서 오류가 있는지 확인하세요:

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 로깅을 비활성화할 수 있습니다.

실행 역할에서 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}:{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 함수의 스팬이 포함된 트레이스가 표시되어야 합니다
트레이스는 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 데이터 플레인

시작하기

기능

ClickStack 관리

가이드

통합 파트너

Rotel을 사용한 ClickStack의 AWS Lambda 로그 모니터링

기존 Lambda 함수와의 통합

사전 요구 사항

옵션 1: AWS Console

옵션 2: AWS CLI

옵션 3: AWS SAM

기본 구성(환경 변수)

고급 구성 (`.env` 파일 사용)

AWS Secrets Manager 또는 Parameter Store 사용

CloudWatch Logs 비활성화(비용 최적화)

OpenTelemetry 자동 계측 추가

예시 애플리케이션

Rotel 커뮤니티에 참여하세요

추가 자료

​기존 Lambda 함수와의 통합

​사전 요구 사항

옵션 1: AWS Console

옵션 2: AWS CLI

옵션 3: AWS SAM

기본 구성(환경 변수)

고급 구성 (.env 파일 사용)

AWS Secrets Manager 또는 Parameter Store 사용

​CloudWatch Logs 비활성화(비용 최적화)

​OpenTelemetry 자동 계측 추가

​예시 애플리케이션

​Rotel 커뮤니티에 참여하세요

​추가 자료

기존 Lambda 함수와의 통합

사전 요구 사항

고급 구성 (`.env` 파일 사용)

CloudWatch Logs 비활성화(비용 최적화)

OpenTelemetry 자동 계측 추가

예시 애플리케이션

Rotel 커뮤니티에 참여하세요

추가 자료