메시지 큐(MQ) 설정 가이드

GIIP 플랫폼과 에이전트 간의 비동기 통신을 담당하는 메시지 큐(RabbitMQ/Azure Service Bus) 설정 방법을 안내합니다.

🔔 메시지 큐 설정 페이지로 이동 →

📋 개요

**메시지 큐(MQ)**는 에이전트가 수집한 방대한 데이터를 백엔드로 안정적으로 전달하고, 사용자 명령을 에이전트에게 비동기적으로 전송하는 핵심 통로입니다. 올바른 MQ 설정은 시스템의 응답성과 데이터 무결성을 보장합니다.

🔍 주요 설정 항목

1. 연결 정보 (Connection Strings)

• Host Address: MQ 서버의 IP 또는 DNS 주소를 입력합니다.
• 인증 정보: 사용자 아이디, 패스워드 또는 공유 액세스 키(Shared Access Key)를 암호화하여 저장합니다.

2. 큐(Queue) 및 토픽(Topic) 관리

• 입력 큐 (Inbound): 에이전트로부터 전송되는 메트릭/이슈 데이터가 쌓이는 경로입니다.
• 출력 큐 (Outbound): 관리자 명령(execCommand)이 에이전트로 전달되는 경로입니다.
• DLQ (Dead Letter Queue): 처리에 실패한 메시지가 격리되는 보관소로, 장애 분석 시 활용됩니다.

3. 메시지 보존 및 재시도 정책

• TTL (Time To Live): 메시지가 큐에 머무를 수 있는 최대 시간을 설정합니다.
• Retry Count: 처리에 실패했을 때 몇 번까지 다시 시도할지 정의합니다. (기본값: 3회)

🛠️ 설정 방법

1. GIIP [시스템 관리] > [MQ 설정] 메뉴로 이동합니다.
2. [Edit Configuration] 버튼을 클릭하여 사용 중인 MQ 엔진 타입을 선택합니다.
3. 제공받은 연결 문자열을 입력하고 [Test Connection]을 눌러 정상 작동 여부를 확인합니다.
4. 설정값을 저장하면 백엔드 및 에이전트 브로커가 자동으로 재시작됩니다.

💡 활용 팁

• 부하 분산: 대규모 인프라 환경에서는 트래픽이 몰리는 큐를 분리하여 병목 현상을 방지하세요.
• 모니터링 연동: 큐에 쌓인 메시지 수(Message Depth)가 급증할 경우 관리자에게 경고 알림이 가도록 설정하는 것이 좋습니다.

API 참조

이 기능의 API 상세 사양은 별도 가이드를 참조하세요.

📘 메시지 큐 기술 사양

문제 해결

증상	원인	해결
[Test Connection]이 실패함	Host Address 또는 인증 정보 오류	연결 문자열과 인증 정보를 다시 확인한 후 재입력합니다
큐에 메시지가 계속 쌓임(Message Depth 급증)	처리 지연 또는 소비 병목	트래픽이 몰리는 큐를 분리하고 모니터링 경고 알림을 설정합니다
처리 실패 메시지가 사라진 것처럼 보임	Retry Count 초과 후 DLQ로 이동	DLQ(Dead Letter Queue)에서 격리된 메시지를 확인하여 장애를 분석합니다
설정 저장 직후 통신이 잠시 중단됨	백엔드 및 에이전트 브로커의 자동 재시작	재시작이 완료될 때까지 대기합니다 (정상 동작)

---

버전: 1.0 최종 업데이트: 2026-03-19 소스 파일: giipv3/public/help/mq-config.ko.md