Hongzi Lab

텔레그램 봇과 채널로 서버 오류 알림 받기

Hongzi

여러 자동화 서비스를 운영하다 보면 성공 로그보다 먼저 봐야 하는 것은 인증 만료와 외부 API 장애다. 현재 운영 환경에서는 이를 확인하기 위해 애플리케이션과 분리된 Docker 기반 auth-monitor를 사용한다. 점검 결과는 PostgreSQL에 남기고, 운영자가 바로 확인해야 하는 상태 변화만 Telegram으로 보낸다.

실제 운영 구조

모니터는 등록된 점검 플러그인으로 YouTube, Instagram, Telegram, R2와 공개 HTTP 엔드포인트를 읽기 전용으로 확인한다. 검사 결과와 실행 회차는 PostgreSQL에 저장하지만 토큰, 쿠키, client secret은 결과·로그·데이터베이스에 저장하지 않는다.

  1. Docker 컨테이너의 스케줄러가 점검 시각을 계산한다.
  2. 각 플러그인이 환경변수 또는 공개 HTTP 응답을 읽어 ok, warn, failed 상태를 만든다.
  3. PostgreSQL의 직전 상태와 비교해 새 장애, 지속 장애, 복구 여부를 판단한다.
  4. 알림이 필요한 상태 변화만 Telegram Bot API의 sendMessage로 전송한다.

실제 운영 중 오류가 발생하면 Telegram 채널에 오류 유형과 발생 단계, 대상 상품, 오류 정보, 재시도 횟수와 알림 시각이 함께 전달된다. EDITOR_FAILED처럼 실패 유형이 표시되므로 운영자는 서버에 먼저 접속하지 않아도 어느 단계에서 문제가 생겼는지 메시지에서 확인할 수 있다.

알림 화면에서는 실패 단계와 재시도 상황을 한 번에 확인하고, 추가 확인이 필요한 경우에만 서버 로그와 해당 작업을 이어서 점검한다.

중복 알림을 줄이는 방식

기본 점검 시각은 KST 기준 00:45, 06:45, 12:45, 18:45다. 스케줄 시각으로 만든 slot_key를 PostgreSQL에 먼저 등록하므로 같은 회차를 두 프로세스가 동시에 실행하는 상황을 막는다.

상태가 정상에서 장애로 바뀌면 즉시 알리고, 같은 장애가 계속되는 동안에는 매 회차 같은 메시지를 보내지 않는다. 기본 24시간이 지난 지속 장애만 다시 알리며, warn이나 failed가 ok로 돌아오면 복구 알림을 보낸다.

Telegram Bot API 호출

실제 전송 코드는 봇 토큰과 알림 채팅 ID를 환경변수에서 읽어 JSON으로 요청한다. 토큰은 URL 구성에만 사용하며 메시지나 데이터베이스에 기록하지 않는다.

{
  "chat_id": "<환경변수에서 읽은 채팅 ID>",
  "text": "<상태 변화와 점검 결과>",
  "disable_web_page_preview": true
}

Telegram 응답의 HTTP 상태와 JSON의 ok 값을 함께 확인한다. 전송 실패 시 성공으로 기록하지 않고 안전한 오류 유형만 로그에 남긴다. 별도의 즉시 재시도 루프는 없으며, 알림 성공 시각이 기록되지 않았기 때문에 다음 예약 점검에서 다시 전송을 시도할 수 있다.

직접 점검하는 방법

배포 전에는 등록된 검사 목록을 확인한 뒤 한 회차를 즉시 실행한다. 이 명령은 토큰을 변경하거나 게시물을 만드는 작업을 하지 않는다.

docker compose run --rm auth-monitor python -m auth_monitor.cli --list-checks
docker compose run --rm auth-monitor python -m auth_monitor.cli --once

테스트 코드에서는 정상→실패 전환 시 알림, 동일 실패의 반복 억제, 24시간 후 재알림, 실패→정상 복구 알림을 각각 검증한다. Telegram 자체 점검도 봇 신원과 채널 관리자 상태를 확인하되 토큰을 결과에 포함하지 않는지 검사한다.

로컬 검증 결과: 2026년 8월 14일, 운영 환경변수와 비밀값을 포함하지 않은 소스 복사본에서 Python 단위 테스트 12개를 실행했고 모두 통과했다. 이 테스트는 실제 Telegram 메시지를 보내는 운영 점검이 아니라 스케줄 계산, 중복 알림 억제, 복구 알림, 토큰 비노출 같은 코드 동작을 검증한다.

다른 자동화에도 같은 알림 구조를 쓰는 이유

알림 코드를 각 수집기와 발행기에 중복해서 넣으면 서비스마다 장애 판단 기준이 달라진다. 점검·상태 저장·Telegram 전송을 별도 프로젝트로 분리하면 애플리케이션이 멈춘 상황도 외부에서 확인할 수 있고, 운영 서비스의 데이터 폴더는 필요한 경우에만 읽기 전용으로 연결할 수 있다.

URL을 Notion에 저장한 뒤 Telegram으로 성공 여부를 확인하는 개인 도구도 같은 원칙을 사용한다. 저장 흐름과 CORS 문제를 해결한 과정은 URL → Notion → Telegram 시스템 제작기에 정리했다.

추천 콘텐츠