View a markdown version of this page

Amazon CloudWatch로 로그 전송 - Amazon CloudWatch
사전 조건로그 그룹 및 소스OTel 로그 파이프라인의 작동 방식로그 수집 사용자 지정Verification(확인)문제 해결

Amazon CloudWatch로 로그 전송

OTel Container Insights는 OpenTelemetry Collector의 로그 파이프라인을 통해 컨테이너 로그를 수집하여 Amazon CloudWatch Logs로 전송합니다. Amazon CloudWatch Observability EKS 추가 기능은 파일 로그 수신기를 사용하여 컨테이너 로그 파일을 테일링하고, Kubernetes 메타데이터로 보강하고, CloudWatch Logs 내보내기를 통해 CloudWatch Logs로 내보내는 OpenTelemetry Collector를 DaemonSet로 배포합니다.

기본 로그 수집에는 추가 설정이 필요하지 않습니다. 로그 수집은 빠른 시작: Amazon EKS의 OTel Container Insights를 준수하는 경우 기본적으로 활성화됩니다.

사전 조건

로그 수집을 구성하기 전에 다음 요구 사항을 충족하는지 확인합니다.

  • 클러스터에 OTel Container Insights가 설치되고 amazon-cloudwatch-observability 추가 기능이 활성화됨

  • IAM 권한: logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents, logs:DescribeLogGroups, logs:DescribeLogStreams(CloudWatchAgentServerPolicy 관리형 정책에 포함됨)

  • 노드 액세스: 수집기에 각 노드의 /var/log/pods에 대한 액세스 권한 필요

로그 그룹 및 소스

다음 표에서는 OTel Container Insights가 생성하는 로그 그룹과 해당 로그 그룹이 수집하는 소스에 대해 설명합니다.

로그 그룹: 소스 내용
/aws/containerinsights/cluster-name/application /var/log/pods/**/*.log 모든 컨테이너 stdout 및 stderr 로그
참고

호스트 및 데이터 플레인 로그는 향후 릴리스에서 사용할 수 있습니다.

OTel 로그 파이프라인의 작동 방식

추가 기능의 OpenTelemetry Collector는 다음 구성 요소가 포함된 로그 파이프라인을 실행합니다.

  • 수신기 - filelog 수신기는 /var/log/pods/의 컨테이너 로그 파일을 테일링합니다.

  • 프로세서 - k8sattributes 프로세서는 Kubernetes 메타데이터로 로그를 보강합니다. batch 프로세서는 내보내기 전에 로그 레코드를 일괄 처리합니다. resource 프로세서는 리소스 속성을 추가합니다.

  • 내보내기 - awscloudwatchlogs 내보내기가 CloudWatch Logs로 로그 레코드를 전송합니다.

로그 보강

파이프라인은 다음 속성으로 모든 로그 레코드를 보강합니다.

  • Kubernetes 리소스 속성 - k8s.pod.name, k8s.namespace.name, k8s.container.name, k8s.node.name, k8s.deployment.name

  • 포드 레이블 - 모든 포드 레이블을 k8s.pod.label.* 속성으로 사용

  • 클라우드 속성 – cloud.region, cloud.account.id, cloud.platform

  • 클러스터 속성 - k8s.cluster.name

로그 수집 사용자 지정

추가 기능 구성 값을 업데이트하여 로그 수집을 사용자 지정할 수 있습니다. 다음 섹션에서는 일반적인 사용자 지정 옵션에 대해 설명합니다.

로그 수집 비활성화

로그 수집을 완전히 비활성화하려면 컨테이너 로그가 비활성화된 상태로 추가 기능 구성을 업데이트합니다.

로그 수집 비활성화

  • 다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"containerLogs":{"enabled":false}}' \
  --resolve-conflicts OVERWRITE

로그 수집에서 네임스페이스 제외

로그 수집에서 특정 네임스페이스를 제외하려면 excludeNamespaces 구성 옵션을 사용합니다.

로그 수집에서 네임스페이스 제외

  • 다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다. 네임스페이스 값을 제외하려는 네임스페이스로 바꿉니다.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"containerLogs":{"enabled":true,"excludeNamespaces":["kube-system","load-testing","monitoring"]}}' \
  --resolve-conflicts OVERWRITE

특정 네임스페이스만 포함

특정 네임스페이스에서만 로그를 수집하려면 includeNamespaces 구성 옵션을 사용합니다.

특정 네임스페이스만 포함

  • 다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다. 네임스페이스 값을 포함하려는 네임스페이스로 바꿉니다.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"containerLogs":{"enabled":true,"includeNamespaces":["production","staging"]}}' \
  --resolve-conflicts OVERWRITE

다중 줄 로그 구문 분석 구성

다중 줄 로그 항목(예: 스택 추적)을 단일 로그 레코드로 결합하려면 첫 번째 줄 패턴으로 다중 줄 구문 분석을 구성합니다.

다중 줄 로그 구문 분석 구성

  • 다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다. firstLinePattern 값을 각 로그 항목의 첫 번째 줄과 일치하는 정규식 패턴으로 바꿉니다.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"containerLogs":{"enabled":true,"multilineConfig":{"firstLinePattern":"^\\d{4}-\\d{2}-\\d{2}|^\\[\\d{4}","parseFormat":"auto"}}}' \
  --resolve-conflicts OVERWRITE

로그 보존 설정

기본적으로 CloudWatch Logs에서 로그 데이터는 무기한으로 보존됩니다. 스토리지 비용을 제어하기 위해 로그 그룹에 보존 정책을 설정할 수 있습니다.

로그 보존 설정

  • 다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다. 30을 로그 보존 일수로 바꿉니다.

    aws logs put-retention-policy \
  --log-group-name "/aws/containerinsights/cluster-name/application" \
  --retention-in-days 30

Verification(확인)

로그 수집이 작동하는지 확인하려면 예상 로그 그룹이 존재하고 데이터가 포함되어 있는지 확인합니다.

로그 수집 확인

  • 다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다.

    aws logs describe-log-groups \
  --log-group-name-prefix "/aws/containerinsights/cluster-name" \
  --query "logGroups[].{Name:logGroupName,StoredBytes:storedBytes}" \
  --output table

    출력에는 로그 그룹 이름과 저장된 바이트 수가 표시됩니다. StoredBytes에 0이 아닌 값은 파이프라인이 로그를 전송하고 있음을 확인합니다.

문제 해결

다음 지침에 따라 일반적인 로그 수집 문제를 해결합니다.

5분 후에 로그 그룹이 생성되지 않음

증상: 5분 후에 CloudWatch Logs에 /aws/containerinsights/cluster-name/application 로그 그룹이 표시되지 않습니다.

원인: 수집기에 로그 그룹 및 로그 스트림을 생성하는 데 필요한 IAM 권한이 없습니다.

해결 방법: 수집기와 연결된 IAM 역할에 CloudWatchAgentServerPolicy 관리형 정책이 연결되어 있는지 확인합니다. 이 정책에는 logs:CreateLogGroup 및 logs:CreateLogStream 권한이 포함되어 있습니다.

애플리케이션 로그 그룹이 있지만 비어 있음

증상: 애플리케이션 로그 그룹이 CloudWatch Logs에 존재하지만 로그 스트림 또는 로그 이벤트가 포함되어 있지 않습니다.

원인:이 문제는 컨테이너가 stdout 또는 stderr에 쓰지 않거나 파일 로그 수신기가 노드에서 /var/log/pods/에 액세스할 수 없을 때 발생합니다.

해결 방법: 다음 단계에 따라 이 문제를 해결합니다.

  1. 애플리케이션 컨테이너가 stdout 또는 stderr에 로그를 쓰는지 확인합니다.

  2. 수집기 DaemonSet 포드에 /var/log/pods용 볼륨 마운트가 있는지 확인합니다.

    kubectl get daemonset -n amazon-cloudwatch -o yaml | grep -A 5 "var/log/pods"

  3. 수집기 로그에서 파일 액세스 오류를 확인합니다.

    kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50 | grep -i "error\|permission"

높은 CloudWatch Logs 비용

증상: CloudWatch Logs 수집 또는 스토리지 비용이 예상보다 높습니다.

원인: 대용량 네임스페이스(예: 로드 테스트 또는 모니터링 네임스페이스)는 대량의 로그를 생성합니다.

해결 방법: 다음 단계에 따라 비용을 줄입니다.

  1. 로그 수집에서 대용량 네임스페이스를 제외합니다. 지침은 로그 수집에서 네임스페이스 제외 섹션을 참조하세요.

  2. 로그 그룹에 보존 정책을 설정하여 이전 로그를 자동으로 삭제합니다. 지침은 로그 보존 설정 단원을 참조하세요.