MQTT 보존(Retained) 메시지 사용과 주의사항

개요

MQTT의 보존(retained) 메시지는 브로커가 특정 토픽에 대해 마지막으로 발행된 메시지를 저장해 신규 구독자에게 즉시 전달하는 기능이다. 이 기능을 잘 이해하면 상태 정보 전달에 유용하지만, 오용하면 오래된 정보가 퍼지거나 예상치 못한 동작을 야기할 수 있다. 초보자도 이해하기 쉽게 동작 원리, 사용법, 주의사항과 문제 해결 방법을 정리한다.

보존 메시지의 기본 원리

동작 방식

보존 메시지는 발행 시 retained 플래그가 설정되면 브로커가 해당 토픽에 메시지를 저장한다. 이후 새로운 구독자가 그 토픽을 구독하면 저장된 마지막 메시지를 즉시 전송한다. 기존 구독자에게는 일반 발행과 동일하게 전달된다.

저장과 삭제 규칙

• 플래그가 설정된 메시지가 도착하면 브로커가 덮어쓰며 저장한다.
• 빈 페이로드로 retained 플래그를 설정하여 발행하면 보존 메시지가 삭제된다.
• 브로커 재시작, 클라이언트 연결 여부와는 별개로 보존 메시지는 브로커의 영구 저장에 남을 수 있다.

mqtt retained 메시지 설명 — 실용 예시

다음 예시는 mqtt.js와 mosquitto 클라이언트에서 보존 메시지를 발행하고 삭제하는 방법이다.

mqtt.js로 보존 메시지 발행

const mqtt = require('mqtt')
const client = mqtt.connect('mqtt://broker.example')
client.on('connect', () => {
  client.publish('home/temperature/last', '22.5', { qos: 1, retain: true })
})

mosquitto_pub으로 보존 메시지 발행 및 삭제

# 보존 메시지 발행
mosquitto_pub -h broker.example -t 'home/temperature/last' -m '22.5' -r

# 보존 메시지 삭제(빈 페이로드에 -r 옵션)
mosquitto_pub -h broker.example -t 'home/temperature/last' -n -r

자주 발생하는 문제와 retained message 문제 해결

문제 1: 오래된 값이 신규 구독자에게 전달됨

의도적으로 보존한 값이 오래되어 의미가 없을 때 신규 구독자가 잘못된 상태로 동작할 수 있다. 이 문제 해결을 위해서는 보존 메시지를 주기적으로 갱신하거나, 메시지에 타임스탬프를 포함해 수신 측에서 유효성 검사를 하도록 설계한다.

문제 2: 잘못된 플래그로 인한 보존

일시적으로 남겨진 보존 메시지가 원인이 되는 경우가 많다. 발행 코드를 점검해 불필요하게 retain 플래그가 설정되는 부분을 제거하고, 이미 남아 있는 메시지는 빈 페이로드로 삭제한다.

문제 3: 와일드카드 구독과의 혼동

와일드카드로 구독하는 경우 여러 토픽의 보존 메시지가 한꺼번에 전달돼 혼란이 생길 수 있다. 이 경우 와일드카드 대신 정확한 토픽 네이밍을 사용하거나 수신 로직에서 토픽별 처리 정책을 둔다.

설계 관점의 권장 사항

• 보존 메시지는 상태 정보(예: 장치의 현재 상태, 마지막으로 알려진 센서값)에만 사용한다. 텔레메트리처럼 빠르게 변화하는 데이터는 보존하지 않는다.
• 메시지에 메타데이터로 타임스탬프와 소스 식별자 포함을 권장한다. 이를 통해 수신 측에서 오래된 메시지를 걸러낼 수 있다.
• 클라이언트는 초기 구독 시 보존 메시지를 처리하는 명확한 로직을 가진다. 예를 들어 초기값 로딩과 실시간 업데이트를 분리한다.
• 테스트 환경에서 발행 후 retained 상태를 확인하는 절차를 표준화한다. 자동화 스크립트로 불필요한 보존 메시지가 남지 않도록 한다.

운영 중 발생한 사례와 해결 절차

운영에서 흔히 보는 사례는 센서 교체 후 이전 장비의 보존 메시지가 남아 잘못된 장비 상태로 표시되는 경우다. 해결 절차는 다음과 같다.

• 현재 보존 메시지 확인: mosquitto_sub로 토픽 구독하여 확인
• 의도치 않은 값이면 빈 메시지로 삭제: mosquitto_pub -n -r 로 삭제
• 새 장비가 정상 값을 발행하도록 초기화 스크립트 추가
• 장비 등록/제거 절차에 보존 메시지 삭제 단계를 포함

최종 점검 체크리스트

• 보존 메시지를 사용할 토픽 목록 정의
• 메시지 페이로드에 타임스탬프와 식별자 포함 여부 확인
• 발행 코드에서 retain 옵션이 필요한 곳만 설정
• 보존 메시지 삭제 방법을 운영 매뉴얼에 명시
• 테스트 시 보존 메시지 상태를 검증하는 자동화 도구 마련

마무리

MQTT 보존 메시지는 적절히 설계하면 시스템 초기화와 상태 전파에서 강력한 도구가 된다. 반면 무분별한 사용은 오래된 데이터 전파나 혼란을 초래하므로, 토픽 설계와 발행 정책, 수신 쪽 검증 로직을 함께 마련하는 것이 중요하다. 위 설명과 절차를 통해 mqtt 보존 메시지 사용법을 이해하고, 발생 가능한 문제에 대한 해결 방안을 적용하면 안정적인 운영에 도움이 된다.