운영과 장애 추적

MQTT 장치에도 로컬 로그가 필요한 이유

MQTT 장치가 정상일 때는 로그의 필요성을 느끼기 어렵습니다. 센서값이 브로커에 올라오고 대시보드에 그래프가 그려지면 모든 것이 괜찮아 보입니다. 하지만 어느 날 데이터가 끊기면 이야기가 달라집니다. 서버에 값이 없다는 사실만으로는 장치가 꺼졌는지, Wi-Fi가 끊겼는지, MQTT 인증이 실패했는지, 센서가 죽었는지 알 수 없습니다.

서버 로그만으로 부족한 순간

서버 로그는 “서버에 도착한 일”만 보여줍니다. 장치가 값을 보내지 못한 이유는 장치 안에 남아 있습니다. 예를 들어 MQTT 브로커에는 아무 로그가 없는데, 실제 원인은 공유기 변경으로 Wi-Fi 비밀번호가 바뀐 것일 수 있습니다. 또는 센서 읽기 함수가 계속 실패해서 publish 자체를 하지 않았을 수도 있습니다.

현장에서 흔한 상황은 더 애매합니다. 장치는 켜져 있고 LED도 깜빡이지만 서버에는 값이 없습니다. USB 시리얼을 연결하려면 케이스를 열어야 하고, 설치 위치가 천장이나 장비실이면 확인 자체가 번거롭습니다. 이때 장치가 최근 상태를 조금이라도 저장하고 있으면 장애 판단 시간이 크게 줄어듭니다.

작은 장치가 남겨야 할 최소 로그

ESP8266이나 ESP32에 서버처럼 많은 로그를 저장할 수는 없습니다. 그래서 모든 문장을 남기기보다, 장애 원인을 가르는 핵심 상태를 남겨야 합니다.

• 부팅 횟수와 마지막 부팅 시각: 전원 불안정이나 watchdog 재부팅을 찾는 기본 정보입니다.
• 리셋 원인: 전원 문제인지, 소프트웨어 watchdog인지, 수동 리셋인지 구분합니다.
• Wi-Fi 연결 성공/실패 횟수: 공유기 거리, 비밀번호 변경, DHCP 문제를 추적합니다.
• MQTT 연결 실패 코드: 인증 실패, 브로커 주소 오류, 네트워크 단절을 구분합니다.
• 마지막 publish 성공 시각: 서버에서 데이터 공백을 볼 때 장치 기준 마지막 성공 시점을 비교합니다.
• 센서 읽기 실패 횟수: 배선 문제, 전원 노이즈, 센서 고장을 구분합니다.
• 현재 펌웨어 버전: 같은 장치 여러 대를 운영할 때 버전 차이로 생기는 문제를 찾습니다.

현실적인 저장 방식: 순환 로그

작은 장치에는 긴 로그 파일보다 순환 로그가 맞습니다. 최근 이벤트 20개, 50개 정도만 남기고 오래된 것은 덮어쓰는 방식입니다. 장애가 생긴 직후 확인할 수 있으면 충분합니다. 이벤트마다 긴 문장을 저장하지 말고, 시간, 이벤트 코드, 짧은 값 정도만 저장하면 됩니다.

로그를 어디서 볼 것인가

로그를 남겨도 꺼내 볼 방법이 없으면 의미가 약합니다. 가장 단순한 방식은 장치가 로컬 웹페이지를 열어 최근 상태를 보여주는 것입니다. 같은 Wi-Fi 안에서 장치 IP로 접속하면 마지막 부팅, Wi-Fi RSSI, MQTT 상태, 센서 실패 횟수를 볼 수 있게 합니다.

화면이 있는 장치라면 OLED에 상태 코드를 보여줄 수도 있습니다. 예를 들어 `WIFI`, `MQTT`, `SENS`, `OK` 같은 짧은 코드를 표시하면 현장에서 스마트폰 없이도 대략적인 상태를 알 수 있습니다. LED만 있는 장치라면 깜빡임 패턴으로 Wi-Fi 실패, MQTT 실패, 센서 실패를 구분할 수 있습니다.

서버로 보내야 하는 상태와 보내지 않아도 되는 상태

모든 로그를 서버로 보내면 트래픽과 저장량이 늘어나고, 장애가 많을 때 오히려 서버가 지저분해집니다. 서버에는 장기 분석에 필요한 값만 보내고, 세부 원인은 장치 내부에 짧게 남기는 방식이 현실적입니다.

• 서버 전송 권장: 마지막 성공 시각, 펌웨어 버전, 배터리 전압, 재부팅 횟수, 연속 실패 횟수.
• 장치 내부 보관 권장: 최근 Wi-Fi 실패 코드, 센서 실패 원인, MQTT 연결 실패 코드, 로컬 디버그 이벤트.
• 보내지 않는 편이 나은 것: Wi-Fi 비밀번호, 토큰, 개인 위치 정보, 내부망 상세 주소.

현장 예시

장비실 온습도 장치가 6시간 동안 서버에 값을 보내지 않았다고 가정해 보겠습니다. 서버만 보면 “데이터 없음”입니다. 하지만 장치 로그에 `BOOT`가 반복되어 있으면 전원 문제를 먼저 봐야 합니다. `WIFI_FAIL`이 많으면 공유기나 신호 세기를 봐야 합니다. `MQTT_FAIL auth`가 있으면 브로커 계정이나 토큰을 확인해야 합니다. `SENSOR_FAIL`만 많고 Wi-Fi와 MQTT는 정상이라면 센서 배선이나 센서 자체를 의심해야 합니다.

이 차이는 실제 유지보수에서 큽니다. 원인을 모르고 현장에 가면 노트북, 센서, 어댑터, 공유기 정보까지 모두 챙겨야 합니다. 로그가 있으면 필요한 부품과 작업 순서를 줄일 수 있습니다.

저장 공간과 균형

로컬 로그는 많을수록 좋은 것이 아니라, 판단에 필요한 만큼만 있어야 합니다. ESP8266처럼 여유가 적은 장치에서는 최근 20~30개 이벤트만 저장해도 충분할 때가 많습니다. ESP32라면 NVS나 SPIFFS, LittleFS를 사용해 조금 더 자세한 기록을 둘 수 있지만, 플래시 수명을 고려해 너무 자주 쓰지 않도록 해야 합니다.

MQTT 장치의 로그 목표는 “개발자가 궁금한 모든 것”이 아니라 “현장에서 다음 행동을 결정할 수 있는 최소 정보”입니다. 이 기준을 잡으면 작은 ESP 장치에서도 충분히 실용적인 장애 추적이 가능합니다.