CloudWatch 에이전트 설치 CloudWatch 에이전트를 사용하여 임베디드 지표 형식 로그 보내기

CloudWatch 에이전트를 사용하여 임베디드 지표 형식 로그 보내기

이 섹션에서는 CloudWatch 에이전트를 설치하고 사용하는 방법을 설명합니다. 이 섹션의 첫 부분에서는 CloudWatch 에이전트를 설치하는 방법을 설명합니다. 이 섹션의 두 번째 부분에서는 CloudWatch 에이전트를 사용하여 임베디드 지표 형식 로그를 전송하는 방법을 설명합니다. 이 방법을 사용하려면 임베디드 지표 형식 로그를 보내려는 AWS 서비스에 대한 CloudWatch 에이전트를 설치해야 합니다. 그런 다음 이벤트 전송을 시작할 수 있습니다. CloudWatch 에이전트는 1.230621.0 이상 버전이어야 합니다.

참고

Lambda 함수에서 로그를 전송하기 위해 CloudWatch 에이전트를 설치할 필요가 없습니다.

Lambda 함수 시간 초과는 자동으로 처리되지 않습니다. 즉, 지표가 플러시되기 전에 함수가 시간 초과되면 해당 호출에 대한 지표가 캡처되지 않습니다.

CloudWatch 에이전트 설치

임베디드 지표 형식 로그를 전송할 각 서비스에 대한 CloudWatch 에이전트를 설치합니다.

EC2에 CloudWatch 에이전트 설치하기

먼저, 인스턴스에 CloudWatch 에이전트를 설치합니다. 자세한 내용은 CloudWatch 에이전트 설치 단원을 참조하세요.

에이전트를 설치한 후에는 임베디드 지표 형식 로그에 대해 UDP 또는 TCP 포트에서 수신 대기하도록 에이전트를 구성합니다. 다음은 기본 소켓 tcp:25888에서 수신 대기하는 이 구성의 예입니다. 에이전트 구성에 대한 자세한 내용은 수동으로 CloudWatch 에이전트 구성 파일 생성 또는 편집 단원을 참조하세요.


{
  "logs": {
    "metrics_collected": {
      "emf": { }
    }
  }
}

Amazon ECS에 CloudWatch 에이전트 설치하기

Amazon ECS에 CloudWatch 에이전트를 배포하는 가장 쉬운 방법은 에이전트를 사이드카로 실행하여 애플리케이션과 동일한 태스크 정의에서 정의하는 것입니다.

에이전트 구성 파일 생성

CloudWatch 에이전트 구성 파일을 로컬에 생성합니다. 이 예제에서 상대 파일 경로는 amazon-cloudwatch-agent.json입니다.

에이전트 구성에 대한 자세한 내용은 수동으로 CloudWatch 에이전트 구성 파일 생성 또는 편집 단원을 참조하세요.


{
  "logs": {
    "metrics_collected": {
      "emf": { }
    }
  }
}

SSM 파라미터 스토어로 구성 푸시

다음 명령을 입력하여 CloudWatch 에이전트 구성 파일을 AWS Systems Manager(SSM) 파라미터 스토어로 푸시합니다.


aws ssm put-parameter \
    --name "cwagentconfig" \
    --type "String" \
    --value "`cat amazon-cloudwatch-agent.json`" \
    --region "{{region}}"

태스크 정의 구성

CloudWatch 에이전트를 사용하고 TCP 또는 UDP 포트를 노출하도록 태스크 정의를 구성합니다. 사용해야 하는 샘플 작업 정의는 네트워킹 모드에 따라 다릅니다.

webapp에서 AWS_EMF_AGENT_ENDPOINT 환경 변수를 지정합니다. 이 기능은 라이브러리에서 사용되며 에이전트가 수신 대기하는 엔드포인트를 가리켜야 합니다. 또한 cwagent에서는 CW_CONFIG_CONTENT를 이전 단계에서 생성한 SSM 구성을 가리키는 “valueFrom” 파라미터로 지정합니다.

이 단원에는 브리지 모드에 대한 예 하나와 호스트 또는 awsvpc 모드에 대한 예 하나가 포함되어 있습니다. Amazon ECS에서 CloudWatch 에이전트를 구성하는 방법에 대한 추가 예는 Github 샘플 리포지토리를 참조하세요.

다음은 브리지 모드의 예입니다. 브리지 모드 네트워킹을 사용 설정한 경우 links 파라미터를 사용하여 에이전트를 애플리케이션에 연결해야 하며 컨테이너 이름을 사용하여 에이전트 주소를 지정해야 합니다.


{
  "containerDefinitions": [
          {
              "name": "webapp",
              "links": [ "cwagent" ],
              "image": "my-org/web-app:latest",
              "memory": 256,
              "cpu": 256,
              "environment": [{
                "name": "AWS_EMF_AGENT_ENDPOINT",
                "value": "tcp://cwagent:25888"
              }],
          },
          {
              "name": "cwagent",
              "mountPoints": [],
              "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
              "memory": 256,
              "cpu": 256,
              "portMappings": [{
                  "protocol": "tcp",
                  "containerPort": 25888
              }],
              "environment": [{
                "name": "CW_CONFIG_CONTENT",
                "valueFrom": "cwagentconfig"
              }],
          }
      ],
}

다음은 호스트 모드 또는 awsvpc 모드의 예입니다. 이러한 네트워크 모드에서 실행할 경우 에이전트는 localhost를 통해 주소를 지정할 수 있습니다.


{
  "containerDefinitions": [
          {
              "name": "webapp",
              "image": "my-org/web-app:latest",
              "memory": 256,
              "cpu": 256,
              "environment": [{
                "name": "AWS_EMF_AGENT_ENDPOINT",
                "value": "tcp://127.0.0.1:25888"
              }],
          },
          {
              "name": "cwagent",
              "mountPoints": [],
              "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
              "memory": 256,
              "cpu": 256,
              "portMappings": [{
                  "protocol": "tcp",
                  "containerPort": 25888
              }],
              "environment": [{
                "name": "CW_CONFIG_CONTENT",
                "valueFrom": "cwagentconfig"
              }],
          }
      ],
}

참고

awsvpc 모드에서는 VPC에 퍼블릭 IP 주소를 제공하거나(Fargate만 해당) NAT 게이트웨이를 설정하거나 CloudWatch Logs VPC 엔드포인트를 설정해야 합니다. NAT 설정에 대한 자세한 내용은 NAT 게이트웨이를 참조하세요. CloudWatch Logs VPC 엔드포인트 설정에 대한 자세한 내용은 인터페이스 VPC 엔드포인트와 함께 CloudWatch Logs 사용 단원을 참조하세요.

다음은 Fargate 시작 유형을 사용하는 작업에 퍼블릭 IP 주소를 할당하는 방법의 예입니다.


aws ecs run-task \ 
--cluster {{cluster-name}} \
--task-definition cwagent-fargate \
--region {{region}} \
--launch-type FARGATE \
--network-configuration "awsvpcConfiguration={subnets=[{{subnetId}}],securityGroups=[{{sgId}}],assignPublicIp=ENABLED}"

권한 확인

태스크를 실행하는 IAM 역할에 SSM 파라미터 스토어에서 읽을 수 있는 권한이 있는지 확인합니다. AmazonSSMReadOnlyAccess 정책을 연결하여 이 권한을 추가할 수 있습니다. 이를 위해 다음 명령을 입력합니다.


aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
--role-name CWAgentECSExecutionRole

Amazon EKS에 CloudWatch 에이전트 설치하기

이 클러스터에 CloudWatch Container Insights를 이미 설치한 경우 이 프로세스의 일부를 건너뛸 수 있습니다.

권한

Container Insights를 아직 설치하지 않았다면 먼저, Amazon EKS 노드에 적절한 IAM 권한이 있는지 확인합니다. CloudWatchAgentServerPolicy가 연결되어 있어야 합니다. 자세한 내용은 CloudWatch에서 Container Insights에 대한 사전 요구 사항 확인 단원을 참조하세요.

ConfigMap 생성

에이전트에 대한 ConfigMap을 생성합니다. ConfigMap은 또한 TCP 또는 UDP 포트에서 수신 대기하도록 에이전트에 지시합니다. 다음 ConfigMap을 사용합니다.


# cwagent-emf-configmap.yaml
apiVersion: v1
data:
  # Any changes here must not break the JSON format
  cwagentconfig.json: |
    {
      "agent": {
        "omit_hostname": true
      },
      "logs": {
        "metrics_collected": {
          "emf": { }
        }
      }
    }
kind: ConfigMap
metadata:
  name: cwagentemfconfig
  namespace: default

Container Insights를 이미 설치한 경우 기존 ConfigMap에 다음 "emf": { } 줄을 추가합니다.

ConfigMap 적용

다음 명령을 입력하여 ConfigMap을 적용합니다.


kubectl apply -f cwagent-emf-configmap.yaml

에이전트 배포

CloudWatch 에이전트를 사이드카로 배포하려면 다음 예와 같이 포드 정의에 에이전트를 추가합니다.


apiVersion: v1
kind: Pod
metadata:
  name: myapp
  namespace: default
spec:
  containers:
    # Your container definitions go here
    - name: web-app
      image: my-org/web-app:latest
    # CloudWatch Agent configuration
    - name: cloudwatch-agent
      image: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest
      imagePullPolicy: Always
      resources:
        limits:
          cpu: 200m
          memory: 100Mi
        requests:
          cpu: 200m
          memory: 100Mi
      volumeMounts:
        - name: cwagentconfig
          mountPath: /etc/cwagentconfig
      ports:
  # this should match the port configured in the ConfigMap
        - protocol: TCP
          hostPort: 25888
          containerPort: 25888
  volumes:
    - name: cwagentconfig
      configMap:
        name: cwagentemfconfig

CloudWatch 에이전트를 사용하여 임베디드 지표 형식 로그 보내기

CloudWatch 에이전트를 설치하고 실행 중인 경우 TCP 또는 UDP를 통해 임베디드 지표 형식 로그를 전송할 수 있습니다. 에이전트를 통해 로그를 전송할 때 다음 두 가지 요구 사항이 있습니다.

로그에는 사용할 로그 그룹을 에이전트에 알려주는 LogGroupName 키가 있어야 합니다.
각 로그 이벤트는 한 줄에 있어야 합니다. 즉, 로그 이벤트에는 줄 바꿈 문자(\n)가 포함될 수 없습니다.

또한 로그 이벤트는 임베디드 지표 형식 사양을 따라야 합니다. 자세한 내용은 사양: 임베디드 지표 형식 단원을 참조하십시오.

임베디드 지표 형식을 사용하여 만든 지표의 경보를 만들려는 경우 임베디드 지표 형식으로 만든 지표의 경보 설정에서 권장 사항을 참조하세요.

다음은 Linux bash 셸에서 수동으로 로그 이벤트를 전송하는 예제입니다. 선택한 프로그래밍 언어에서 제공하는 UDP 소켓 인터페이스를 대신 사용할 수 있습니다.


echo '{"_aws":{"Timestamp":1574109732004,"LogGroupName":"Foo","CloudWatchMetrics":[{"Namespace":"MyApp","Dimensions":[["Operation"]],"Metrics":[{"Name":"ProcessingLatency","Unit":"Milliseconds","StorageResolution":60}]}]},"Operation":"Aggregator","ProcessingLatency":100}' \
> /dev/udp/0.0.0.0/25888

참고

포함된 지표 형식을 사용하면 계정의 AWS/Logs 네임스페이스에 게시된 지표별로 EMF 로그 처리를 추적할 수 있습니다. 이를 사용하여 EMF에서 실패한 지표 생성과 구문 분석 또는 검증으로 인한 오류 발생 여부를 추적할 수 있습니다. 자세한 내용을 알아보려면 CloudWatch 지표를 사용한 모니터링을 참조하세요.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

PutLogEvents API를 사용하여 수동으로 생성된 임베디드 지표 형식 로그 전송

AWS Distro for OpenTelemetry에서 임베디드 지표 형식 사용하기