Google Cloud Pub/Sub | 사용 매뉴얼 | 로그프레소 스토어

개요

GCP Pub/Sub 앱은 구글 클라우드 Pub/Sub 구독에서 메시지를 수신하고, 로그프레소에서 메시지를 조회하거나 게시하는 기능을 제공합니다.

Pub/Sub는 메시지를 실어 나르는 전송 경로일 뿐이며 메시지의 형식을 정의하지 않습니다. 이 앱은 수신한 메시지를 원본 문자열 그대로 적재하며, 감사 로그나 JSON 등 특정 형식으로 해석하는 일은 별도의 파서나 쿼리 명령어가 담당합니다.

앱이 제공하는 확장 명령어는 다음 세 가지입니다. 메시지 소비 여부가 가장 중요한 차이입니다.

명령어	용도	메시지 소비	대상
`gcp-pubsub-pull`	구독 내용 확인	삭제되지 않음	구독
`gcp-pubsub-messages`	지정한 시간 동안 실시간 수신	삭제됨	구독
`gcp-pubsub-publish`	주제에 메시지 게시	해당 없음	주제

수집기가 동작 중인 구독을 확인할 때는 gcp-pubsub-pull을 사용하십시오. 각 명령어의 옵션과 출력 필드는 명령어별 매뉴얼을 참고하십시오.

수집기를 재시작하지 않아도 아래 변경은 자동으로 반영됩니다.

연결이 끊긴 경우에도 1분마다 재연결을 시도합니다. 구독을 새로 만들거나 권한을 부여하는 등 GCP 쪽에서 원인을 해소하면 최대 1분 안에 다시 수집을 시작합니다.

수집기가 적재하는 값은 원본 문자열입니다. 구조화된 필드로 보려면 두 가지 방법이 있습니다.

수집기 — 해당 로그 형식에 맞는 앱(예: Google Cloud 감사)을 설치하고, 그 앱이 제공하는 수집 모델을 선택하십시오. 수집기 자체에는 파싱 명령어를 지정할 수 없습니다.
쿼리 — gcp-pubsub-pull 결과에 parsejson 이나 parse 를 연결합니다.

수집기가 동작 중인 상태로 앱을 교체하면 이전 버전이 생성한 연결이 정리되지 못한 채 남아, 로그 파일이 비정상적으로 증가할 수 있습니다. 이 상태는 수집기를 중지해도 해소되지 않으며 로그프레소 재시작이 필요합니다.

수집기 중지 → 앱 설치 → 수집기 시작 순서로 진행하십시오.

수집기 목록의 오류 항목을 먼저 확인하십시오. 자주 나타나는 오류는 다음과 같습니다.

오류	원인	조치
`NOT_FOUND: Resource not found`	구독이 존재하지 않음	구독 ID 확인. 주제 ID를 입력하지 않았는지 확인
`PERMISSION_DENIED`	서비스 계정 권한 부족	해당 구독에 `Pub/Sub 구독자` 역할 부여
`connect profile not found`	접속 프로파일이 삭제됨	프로파일을 다시 만들거나 수집기 설정 수정
`keyJson cannot be null or blank`	접속 프로파일의 JSON 키가 비어 있음	접속 프로파일에 키 파일 내용 입력
`Error reading credentials from stream`	JSON 키 형식이 잘못됨	키 파일 전체를 다시 복사해 입력

권한 관련 오류는 액세스 제어 문서를 참고하십시오. 메시지를 수신하려면 Pub/Sub 구독자(roles/pubsub.subscriber)가 필요하며 Pub/Sub 뷰어로는 부족합니다.

오류가 없다면 구독에 메시지가 도착하지 않는 것입니다. gcp-pubsub-pull 로 구독을 직접 확인하고, 비어 있다면 메시지를 게시하는 쪽(로그 라우터 싱크 등)의 설정을 점검하십시오.

같은 구독을 다른 소비자가 함께 사용하고 있는지 확인하십시오. 다른 수집기, 실행 중인 gcp-pubsub-messages 쿼리, 구글 클라우드 콘솔의 메시지 가져오기 기능이 모두 해당합니다.

수집 모델의 파서가 해당 메시지를 해석하지 못한 경우입니다. gcp-pubsub-pull 로 원본을 확인해 메시지 형식이 파서가 기대하는 형식과 일치하는지 점검하십시오.

최대 1분이 걸립니다. 수집기는 프로파일 변경을 감지하면 다음 재연결 주기에 새 자격증명으로 다시 연결합니다. 1분이 지나도 반영되지 않으면 수집기 오류 항목을 확인하십시오.