190. (Aws/Amazon) [Amazon CloudWatch] CloudWatch 특정 로그 스트림에서 로그 이벤트 를 조회 GetLogEvents API 설명 정리

---

[개발 환경 설정]

​

개발 환경 : Aws / Amazon Web Services

​

제 목 : [Amazon CloudWatch] CloudWatch 특정 로그 스트림에서 로그 이벤트 를 조회 GetLogEvents API 설명 정리

​

 

---

[설명 정리]

​

// --------------------------------------------------------------------------------------
[개발 및 환경]
// --------------------------------------------------------------------------------------

- 인프라 : Aws / Amazon Web Services


- 기술 구분 : Aws / CloudWatch / GetLogEvents


- 사전) AWS CloudWatch 간단 설명 : 

  >> Aws CloudWatch 는 Amazon Web Services (AWS) 리소스 및 AWS 에서 실행되는 애플리케이션을 실시간으로 모니터링 할 수 있는 서비스입니다

  >> Aws CloudWatch 를 사용하면 시스템 전체의 리소스 사용률, 애플리케이션 성능, 운영 상태를 파악할 수 있습니다

  >> Aws CloudWatch 와 함께 사용할 수 있는 서비스 : 

    - Amazon Simple Notification Service (Amazon SNS) : CloudWatch 와 함께 Amazon SNS를 사용하여 구독 중인 엔드포인트 또는 클라이언트에 메시지를 전달 또는 전송하는 것을 조정하고 관리합니다

    - Amazon EC2 Auto Scaling : Amazon EC2 Auto Scaling 과 함께 CloudWatch 경보를 사용하여 사용자 정의 정책, 상태 확인, 일정에 따라 Amazon EC2 인스턴스를 자동으로 시작하거나 종료할 수 있습니다

    - AWS CloudTrail : AWS CloudTrail 을 사용해 AWS Management Console, AWS CLI 및 기타 서비스에서 수행한 호출을 포함하여 계정의 Amazon CloudWatch API에 대한 호출을 모니터링할 수 있습니다    

    - AWS Identity and Access Management (IAM) : IAM 을 사용하여 AWS 리소스를 사용할 수 있는 사용자를 제어(인증)하고 해당 사용자가 사용할 수 있는 리소스 및 사용 방법을 제어(권한 부여)할 수 있습니다

// --------------------------------------------------------------------------------------






// --------------------------------------------------------------------------------------
[설 명] 
// --------------------------------------------------------------------------------------

1. GetLogEvents 는 특정 로그 스트림 (Log Stream) 에서 로그 이벤트 (Log Events) 를 조회하는 API 입니다.


2. GetLogEvents API 는 시간 범위 필터링, 페이지네이션, 방향 설정 등을 지원하며, CloudWatch Logs에서 가장 기본적인 로그 조회 기능을 제공합니다.


3. GetLogEvents 주요 기능 : 

  >> 특정 로그 스트림의 로그 이벤트 조회 : 

    - 지정한 logGroupName(또는 ARN) + logStreamName 조합으로 로그 이벤트를 조회합니다.

  >> 시간 범위 필터링 지원 : 

    - startTime(포함) ~ endTime(미포함) 범위로 조회 가능
    - Unix epoch milliseconds 기준

  >> 최대 10,000개 또는 1MB까지 한 페이지 반환 :

    - 페이지 크기는 1MB 또는 10,000개의 이벤트 중 먼저 도달한 조건으로 결정됩니다.
    - 페이지는 부분 채워짐 또는 빈 페이지일 수 있음

  >> 양방향 페이지네이션 지원 : 

    - nextForwardToken / nextBackwardToken 반환
    - 현재 요청에서 전달한 token과 반환된 token이 다르면 더 가져올 로그가 있음

  >> 헤드부터 읽기 (startFromHead) 옵션 : 

    - startFromHead = true → 오래된 이벤트부터 읽기
    - 단, endTime 없이 startFromHead를 true로 하면 로그가 계속 추가될 경우 페이지네이션이 끝나지 않을 수 있음

  >> 로그 변환 (transform) 적용되지 않은 원본 로그만 반환 :

    - 로그 변환 (Transform) 이 설정된 경우에도 GetLogEvents 는 원본 로그만 반환
    - 변환된 로그를 보고 싶으면 Logs Insights 쿼리를 사용해야 함


4. ✅ GetLogEvents 요청 전문

  >> GetLogEvents 요청 JSON 예시 :
  
  {
    "logGroupName": "string",
    "logGroupIdentifier": "string",
    "logStreamName": "string",
    "startTime": number,
    "endTime": number,
    "nextToken": "string",
    "limit": number,
    "startFromHead": boolean,
    "unmask": boolean
  }

  >> logGroupName / logGroupIdentifier : 로그 그룹 이름 또는 ARN (둘 중 하나만 사용 가능)

  >> logStreamName : 조회할 로그 스트림 이름

  >> startTime : 조회 시작 시각(ms)

  >> endTime : 조회 종료 시각(ms)

  >> nextToken : 페이지네이션 token

  >> startFromHead : true면 오래된 로그부터, false면 최신 로그부터

  >> limit : 조회할 최대 로그 개수 (1~10,000)


5. ✅ GetLogEvents 응답 전문

  >> GetLogEvents 응답 JSON 예시 : 

  {
    "events": [
      {
        "timestamp": 1739993225000,
        "message": "2026-02-20T07:27:05.000Z\tab12cd34-x9ff-4e11-af11-6a0edd12efcc\tINFO\tProcessing completed for user test01\n",
        "ingestionTime": 1739993226123
      },
      {
        "timestamp": 1739993227345,
        "message": "END RequestId: ab12cd34-x9ff-4e11-af11-6a0edd12efcc\n",
        "ingestionTime": 1739993228456
      }
    ],
    "nextForwardToken": "f/9038575649823746598237",
    "nextBackwardToken": "b/9038575649823746598237"
  }


6. ❌ GetLogEvents 호출 주요 에러 발생 코드 : 

  >> ThrottlingException : CloudWatch 에서 과한 API 호출(스크립트/자동화)이 있을 때 발생
                
  >> ResourceNotFoundException : 존재하지 않는 logGroupName 또는 logStreamName 지정 시 발생
                
  >> InvalidParameterException : logGroupIdentifier 와 logGroupName 을 동시에 지정한 경우 (문서에서 금지) / limit 값이 1~10,000 범위를 벗어날 경우 / 잘못된 token 전달
                
  >> ServiceUnavailableException : CloudWatch Logs 서비스의 임시 장애 시 발생

  >> AccessDeniedException : IAM 권한 부족으로 API 호출이 거부될 때


7. ✅ GetLogEvents 호출 자바스크립트 예시 소스 코드 : 

<script src="https://sdk.amazonaws.com/js/aws-sdk-2.1416.0.min.js"></script>

<script>

  // [AWS 인증 변수 선언]        
  const accessKey = 'AK..A6';
  const secretKey = 'mP..5J';
  const region = 'ap-northeast-2';


  // [AWS 로그 변수 선언] 
  const logGroupName = '/aws/lambda/device-queue-manager';
  const logStreamName = '2026/02/19/[$LATEST]94a6a6cff46b4cf8b08bdb2371012b2f';


  window.onload = async function() {

    // -----------------------------------------
    // [AWS.config 지정]
    // -----------------------------------------  
    AWS.config.update({
      region: region,          
      accessKeyId: accessKey,
      secretAccessKey: secretKey
    });


    // -----------------------------------------
    // [AWS 객체 생성]
    // -----------------------------------------
    const aws = AWS.CloudWatchLogs();


    // -----------------------------------------
    // Aws CloudWatch Logs 로그 이벤트 조회 수행
    // -----------------------------------------
    // AWS 참고 사이트 : https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_GetLogEvents.html
    // ----------------------------------------- 
    const param = { // ✅ Request_파라미터
      logGroupName: logGroupName, // 로그 그룹 명칭
      logStreamName: logStreamName, // 로그 그룹 내에 포함 된 스트림 명칭
      startFromHead: true, // 오래된 로그부터 보려면 true, 최신부터 보려면 false
      limit: 5000 // 반환되는 로그 이벤트의 최대 개수 (최소값 1, 최대값 10000)
    };

    aws.getLogEvents( param , (err, data) => {
      if (err) console.error(err);
      else console.log(JSON.stringify(data));
    });

  };

</script>

// --------------------------------------------------------------------------------------






// --------------------------------------------------------------------------------------
[참고 사이트]
// --------------------------------------------------------------------------------------

[Amazon CloudWatch] Aws CloudWatch 클라우드 와치 개념 및 설정 정리 - Aws 애플리케이션 실시간으로 모니터링 서비스

https://kkh0977.tistory.com/7920

https://blog.naver.com/kkh0977/223834321984?trackingCode=blog_bloghome_searchlist


[Amazon 모니터링 및 로깅 서비스] AWS CloudWatch 와 CloudTrail 차이점 정리

https://kkh0977.tistory.com/8143

https://blog.naver.com/kkh0977/223934869835?trackingCode=blog_bloghome_searchlist


[Amazon CloudWatch] DescribeLogGroups AWS CloudWatch Logs 로그 그룹 목록 조회 API 설명 정리

https://kkh0977.tistory.com/8640

https://blog.naver.com/kkh0977/224188525167

// --------------------------------------------------------------------------------------

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/7920

49. (Aws/Amazon) [Amazon CloudWatch] Aws CloudWatch 클라우드 와치 개념 및 설정 정리 - Aws 애플리케이션 실시

---