RabbitMQ 큐 관리를 위한 필수 명령어: 선언, 목록 조회, 삭제
`rabbitmqctl` 명령줄 인터페이스를 사용하여 필수 큐 관리를 마스터하세요. 이 실용적인 가이드는 일일 RabbitMQ 관리에 필요한 기본 작업을 다룹니다: 적절한 내구성 설정으로 새 큐 선언, 사용자 정의 메트릭(`messages_ready`, `consumers`, `memory`)을 사용한 큐 목록 조회로 효과적인 모니터링, 운영 백로그 관리를 위한 안전한 큐 삭제 또는 비우기. 안정적이고 성능 좋은 메시징 인프라를 보장하기 위한 정확한 명령어와 모범 사례를 알아보세요.
RabbitMQ 큐 관리를 위한 필수 명령어: 선언, 목록 조회, 삭제
RabbitMQ에서 큐 관리는 장애 상황에서 직접 해보기 전까지는 간단해 보입니다. 큐에는 이름, 가상 호스트, 인수, 소비자, 바인딩, 메시지, 그리고 때로는 정책이 계층적으로 적용됩니다. 잘못된 큐를 삭제하거나 잘못된 속성으로 선언하면 브로커 장애만큼 빠르게 애플리케이션을 중단시킬 수 있습니다.
아래 명령어들은 일상적인 작업에 초점을 맞춥니다: 인프라를 준비해야 할 때 큐를 선언하고, 브로커 상태를 파악해야 할 때 큐 목록을 조회하며, 의도적으로 무언가를 제거하려 할 때 큐를 삭제하거나 비웁니다. 예제는 rabbitmqctl을 사용하지만, 관리 UI나 HTTP API를 사용할 때도 동일한 주의가 필요합니다.
사전 요구 사항 및 rabbitmqctl 도구
이 글에서 설명하는 명령어를 실행하려면 RabbitMQ 관리 도구가 설치된 머신에 명령줄로 접근할 수 있거나, rabbitmqctl이 대상 클러스터에 연결할 수 있어야 합니다. 이러한 관리 작업을 수행하려면 일반적으로 권한이 필요합니다.
rabbitmqctl 명령어의 일반적인 구문은 다음과 같습니다:
rabbitmqctl <command> [arguments]
아래 모든 예제는 기본 가상 호스트(/)를 가정합니다. 큐가 다른 vhost에 있는 경우 -p <vhost_name>을 추가하세요. /prod의 orders와 /staging의 orders는 서로 다른 큐이기 때문에 이는 중요합니다.
1. 새 큐 선언 (declare_queue)
큐 선언은 브로커에 큐를 생성하는 과정입니다. 일반적으로 큐는 연결 시 클라이언트 애플리케이션에 의해 선언되지만, rabbitmqctl을 통한 관리적 선언은 설정, 테스트 또는 클라이언트 연결이 설정되기 전에 매우 특정한 큐를 정의하는 데 유용합니다.
declare_queue 명령어를 사용하면 내구성, 독점성, 자동 삭제와 같은 필수 큐 속성을 정의할 수 있습니다.
기본 큐 선언
가장 간단한 명령어는 기본 설정으로 큐를 선언합니다. 현재 RabbitMQ CLI 구문에서 큐 속성은 키-값 쌍으로 전달됩니다:
rabbitmqctl declare_queue name=my_new_queue durable=false
큐 속성 정의
주요 매개변수는 큐의 지속성과 수명 주기를 제어하는 데 사용됩니다:
| 매개변수 | 설명 | 기본값 | 근거 |
|---|---|---|---|
durable |
true인 경우 큐 정의가 브로커 재시작 후에도 유지됩니다. |
false |
시스템 장애에서 살아남아야 하는 큐에 중요합니다. |
exclusive |
true인 경우 큐는 선언한 연결에서만 소비할 수 있으며 해당 연결이 닫히면 삭제됩니다. |
false |
임시적이고 개인적인 리소스에 사용됩니다. |
auto_delete |
true인 경우 마지막 소비자가 연결을 끊으면 큐가 삭제됩니다. |
false |
단기적이고 일시적인 큐에 유용합니다. |
예제: 내구성 있는 큐 선언
내구성 있는 큐 정의는 브로커 재시작 후에도 유지됩니다. 메시지 생존은 메시지 전달 모드와 저장 동작에도 의존하므로, 내구성 있는 큐가 모든 메시지가 영구적이라는 것을 보장하지는 않습니다.
rabbitmqctl declare_queue name=production_durable_queue durable=true
예제: 임시 자동 삭제 큐 선언
rabbitmqctl declare_queue name=temp_worker_queue auto_delete=true
팁: 큐가 이미 존재하는 경우,
declare_queue는 지정된 속성이 기존 큐의 속성과 일치하는 경우에만 성공합니다. 속성이 다르면 명령어가 실패하여 우발적인 잘못된 구성을 방지합니다.
이 실패는 유용합니다. 애플리케이션이 내구성 있는 쿼럼 큐를 기대하는데 운영자가 실수로 동일한 이름의 일시적인 클래식 큐를 선언하면, RabbitMQ는 조용히 의미를 변경하는 대신 불일치를 거부해야 합니다.
2. 큐 목록 조회 및 검사 (list_queues)
큐 상태를 모니터링하는 것은 빈번한 관리 작업입니다. list_queues 명령어는 매우 유연하여, 필요한 메트릭만 정확히 지정할 수 있어 정보 과부하를 방지합니다.
기본 목록 조회
기본적으로 list_queues는 큐 이름, 총 메시지 수, 소비자 수와 같은 일반적인 열을 표시합니다. 운영 작업의 경우 필요한 정확한 열을 요청하는 것이 좋습니다.
rabbitmqctl list_queues
출력 예시:
Timeout: 60.0 seconds...
Listing queues for vhost /
name messages consumers
my_new_queue 0 1
production_durable_queue 150 2
특정 큐 속성 목록 조회
더 깊은 운영 통찰력을 얻기 위해 공백으로 구분된 열 이름 목록을 지정할 수 있습니다. 이는 높은 메시지 수나 메모리 사용량 문제를 해결하는 데 중요합니다.
모니터링을 위한 필수 열:
| 열 이름 | 설명 |
|---|---|
messages_ready |
전달 준비가 된 메시지(소비 가능). |
messages_unacknowledged |
전달되었지만 소비자가 아직 확인하지 않은 메시지. |
consumers |
큐에 연결된 활성 소비자 수. |
memory |
노드에서 큐의 예상 메모리 사용량(바이트). |
policy |
큐에 적용된 정책 이름. |
state |
큐의 운영 상태(예: running, flow, idle). |
type |
큐 유형(노출하는 RabbitMQ 버전에서 classic 또는 quorum 등). |
예제: 상세 큐 검사
현재 백로그, 소비자 상태 및 정책 적용을 확인하려면 다음을 사용하세요:
rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers memory policy
숫자를 함께 읽으세요. messages_ready가 높고 소비자가 0인 큐는 일반적으로 연결된 소비자가 없음을 의미합니다. 준비 메시지는 적지만 messages_unacknowledged가 높은 큐는 메시지를 받았지만 확인하지 않는 소비자를 가리킵니다. 이는 느린 작업, 충돌한 워커, 과도한 프리페치 수 또는 ack/nack을 호출하지 않는 버그 때문일 수 있습니다.
특정 가상 호스트의 큐 목록 조회
기본 가상 호스트 외부의 큐를 확인해야 하는 경우 -p 플래그를 사용하세요.
rabbitmqctl list_queues -p /api_vhost name messages consumers
3. 큐 삭제 및 비우기 (delete_queue 및 purge_queue)
큐가 더 이상 사용되지 않거나 재설정해야 하는 경우, 전체 큐 구조를 삭제하거나 구조는 유지하면서 내용물만 비우는 두 가지 주요 옵션이 있습니다.
큐 삭제 (delete_queue)
delete_queue 명령어는 큐와 현재 저장된 모든 메시지를 영구적으로 제거합니다. 이 작업은 되돌릴 수 없습니다.
rabbitmqctl delete_queue my_old_queue
경고: 데이터 손실 위험 실행 전에 큐가 비어 있거나 내용물이 더 이상 필요하지 않은지 항상 확인하세요. 보류 중인 메시지가 있는 큐를 삭제하면 해당 메시지가 즉시 영구적으로 손실됩니다.
큐 내용물 비우기 (purge_queue)
큐 구조(바인딩, 내구성, 정책)는 유지해야 하지만 모든 메시지를 지워야 하는 경우(예: 잘못된 작업의 백로그를 지우기 위해) purge_queue를 사용하세요.
rabbitmqctl purge_queue my_stuck_queue
이 명령어는 큐 정의를 삭제하지 않고 큐에서 준비 메시지를 제거합니다. 이미 소비자에게 전달되어 확인을 기다리는 메시지는 비우기로 단순히 지워지지 않습니다. 해당 소비자가 연결을 끊거나 재큐잉이 활성화된 상태에서 메시지를 거부하면 일부 메시지가 다시 나타날 수 있습니다. 심각한 정리 중에는 먼저 소비자를 중지하거나 드레인하여 무엇을 비우고 있는지 확인하세요.
다른 VHost의 큐 처리
올바른 큐를 삭제하거나 비우려면 큐가 기본 컨텍스트에 없는 경우 항상 가상 호스트를 지정하세요.
# 특정 가상 호스트의 큐 삭제
rabbitmqctl delete_queue -p /testing_vhost temp_test_queue
삭제하기 전에 저는 보통 다음을 실행합니다:
rabbitmqctl list_queues -p /testing_vhost name messages_ready messages_unacknowledged consumers
이 한 번의 확인으로 많은 실수(잘못된 vhost, 예상치 못한 소비자, 또는 아직 처리 중인 작업이 있는 큐)를 잡아낼 수 있습니다.
필수 명령어 요약
이 표는 일일 RabbitMQ 운영에 사용되는 핵심 큐 관리 명령어를 요약합니다:
| 작업 | 명령어 | 목적 |
|---|---|---|
| 선언 | rabbitmqctl declare_queue name=Q durable=true |
정의된 속성으로 새 큐를 생성합니다. |
| 검사 | rabbitmqctl list_queues name messages consumers |
큐와 특정 운영 메트릭을 나열합니다. |
| 삭제 | rabbitmqctl delete_queue Q |
큐와 준비 메시지를 영구적으로 제거합니다. |
| 정리 | rabbitmqctl purge_queue Q |
구조는 유지하면서 큐에서 준비 메시지를 지웁니다. |
안전한 습관은 간단합니다: 의심스러우면 항상 vhost를 포함하고, 파괴적인 명령어 전에 검사하며, 큐 선언이 애플리케이션 계약의 일부임을 기억하세요. 큐 유형, 내구성, 자동 삭제 동작 및 인수는 스키마처럼 취급해야 하며, 단순한 런타임 세부 사항처럼 취급해서는 안 됩니다.