본문으로 바로가기
본문으로 바로가기

AWS Lambda

이 가이드에서 통합하는 항목:

✅ 로그(Logs)✅ 메트릭(Metrics)✅ 트레이스(Traces)

OpenTelemetry Lambda 레이어 설치​

OpenTelemetry 프로젝트에서는 다음 목적을 위해 별도의 Lambda 레이어를 제공합니다:

  1. OpenTelemetry 자동 계측으로 Lambda 함수 코드를 자동으로 계측하기.
  2. 수집된 로그, 메트릭, 트레이스를 ClickStack으로 전달하기.

언어별 자동 계측 레이어 추가​

언어별 자동 계측 Lambda 레이어는 해당 언어용 OpenTelemetry 자동 계측 패키지를 사용하여 Lambda 함수 코드를 자동으로 계측합니다.

각 언어와 리전마다 고유한 레이어 ARN이 있습니다.

Lambda가 이미 OpenTelemetry SDK로 계측되어 있는 경우, 이 단계는 건너뛰어도 됩니다.

시작하려면:

  1. Layers 섹션에서 "Add a layer"를 클릭합니다.
  2. ARN을 직접 지정하는 옵션을 선택한 후 언어에 맞는 ARN을 선택합니다. 이때 <region>을 사용 중인 리전으로 교체해야 합니다 (예: us-east-2):
arn:aws:lambda:<region>:184161586896:layer:opentelemetry-nodejs-0_7_0:1

레이어의 최신 릴리스는 OpenTelemetry Lambda Layers GitHub 저장소에서 확인할 수 있습니다.

  1. Lambda 함수에서 "Configuration" > "Environment variables" 아래에 다음 환경 변수를 설정합니다.
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
OTEL_PROPAGATORS=tracecontext
OTEL_TRACES_SAMPLER=always_on

OpenTelemetry collector Lambda 레이어 설치​

collector Lambda 레이어를 사용하면 exporter 지연(latency)으로 인한 응답 시간 영향 없이 Lambda 함수에서 ClickStack으로 로그, 메트릭, 트레이스를 전달할 수 있습니다.

collector 레이어를 설치하려면:

  1. Layers 섹션에서 「Add a layer」를 클릭합니다.
  2. 「Specify an ARN」을 선택한 다음 아키텍처에 맞는 ARN을 선택합니다. 이때 <region>을 사용하는 리전으로 교체해야 합니다(예: us-east-2):
arn:aws:lambda:<region>:184161586896:layer:opentelemetry-collector-amd64-0_8_0:1
  1. 다음 collector.yaml 파일을 프로젝트에 추가하여 collector가 데이터를 ClickStack으로 전송하도록 구성합니다:
# collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 'localhost:4317'
      http:
        endpoint: 'localhost:4318'

processors:
  batch:
  decouple:

exporters:
  otlphttp:
    endpoint: "<YOU_OTEL_COLLECTOR_HTTP_ENDPOINT>"
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]
  1. 다음 환경 변수를 추가합니다:
OPENTELEMETRY_COLLECTOR_CONFIG_FILE=/var/task/collector.yaml

설치 확인​

레이어를 배포한 후에는 이제 Lambda 함수에서 발생한 트레이스가 HyperDX에서 자동으로 수집되어 표시됩니다. decouple 및 batching processor는 텔레메트리 수집에 지연을 유발할 수 있으므로, 트레이스가 표시되는 데 시간이 걸릴 수 있습니다. 사용자 정의 로그나 메트릭을 전송하려면, 사용 중인 언어 전용 OpenTelemetry SDKS를 사용해 코드를 계측해야 합니다.

문제 해결​

사용자 정의 계측이 전송되지 않음​

수동으로 정의한 trace 또는 다른 텔레메트리 데이터가 표시되지 않는다면, 호환되지 않는 버전의 OpenTelemetry API 패키지를 사용하고 있을 수 있습니다. OpenTelemetry API 패키지의 버전이 AWS Lambda에 포함된 버전과 같거나 더 낮은 버전인지 확인하십시오.

SDK 디버그 로그 활성화​

OpenTelemetry SDK의 디버그 로그를 활성화하려면 OTEL_LOG_LEVEL 환경 변수를 DEBUG로 설정합니다. 이렇게 하면 자동 계측 계층이 애플리케이션을 정상적으로 계측하고 있는지 확인하는 데 도움이 됩니다.

콜렉터 디버그 로그 활성화​

콜렉터 관련 문제를 디버깅하려면 콜렉터 설정 파일을 수정하여 logging exporter를 추가하고, 텔레메트리 로그 레벨을 debug로 설정하여 콜렉터 람다 레이어에서 더 자세한 로그가 출력되도록 할 수 있습니다.

# collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 'localhost:4317'
      http:
        endpoint: 'localhost:4318'

exporters:
  logging:
    verbosity: detailed
  otlphttp:
    endpoint: "<YOU_OTEL_COLLECTOR_HTTP_ENDPOINT>"
    compression: gzip

service:
  telemetry:
    logs:
      level: "debug"
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]
    metrics:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]
    logs:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]