실패한 자동화 작업에서 텔레그램 알림 보내기

실패 알림은 짧고 다시 손댈 수 있어야 한다

실패한 자동화 작업에서 텔레그램으로 보내야 하는 건 긴 로그가 아니다. 내 경우에는 “무슨 작업이 실패했는지”, “어디까지 갔는지”, “다음에 어디를 보면 되는지” 이 세 가지만 있어야 다시 앉아서 바로 이어갈 수 있었다.

처음엔 그냥 에러 로그를 통째로 보내면 되겠다고 생각했다. 그런데 막상 받아보면 텔레그램 방 안에서 로그는 너무 길고, 정작 필요한 줄은 묻힌다. 알림은 디버깅 화면이 아니라 호출벨에 가깝다. 보고 “아, 저 작업이 저 지점에서 죽었구나” 정도만 바로 알면 된다.

메시지에는 실패 원인보다 위치를 먼저 넣는다

실패 원인은 틀릴 수 있다. 스크립트가 뱉은 에러 한 줄만 보고 원인을 단정하면 오히려 돌아간다. 대신 실패한 위치를 정확히 적어두면 나중에 로그를 다시 열 때 시간이 덜 샌다.

내가 넣고 싶었던 항목은 대충 이 정도였다.

항목	왜 넣는가	예시
작업 이름	여러 자동화가 있을 때 구분하려고	content-pipeline
실행 단계	어디까지 성공했는지 보려고	publish
실패 시각	예약 작업이면 같은 실패가 반복됐는지 보려고	2026-07-26 03:00
커밋 또는 버전	코드가 바뀐 뒤 생긴 문제인지 보려고	66f728c
로그 위치	텔레그램에서 다 보지 않고 원본을 열려고	logs/publish.log
다음 행동	나중의 내가 바로 움직이게 하려고	로그 마지막 50줄 확인

메시지 예시는 이런 느낌이면 충분하다.

[실패] content-pipeline / publish
시각: 2026-07-26 03:00
위치: blog/content-pipeline
버전: 66f728c
로그: logs/publish.log
다음: 로그 마지막 50줄부터 확인

여기서 욕심내서 원인 추정까지 길게 붙이면 알림이 점점 리포트처럼 변한다. 텔레그램 알림은 리포트가 아니었다. 실패를 발견하고, 다시 들어갈 문을 알려주는 정도가 딱 맞았다.

컨텍스트 값은 스크립트 안에서 만들 수 있는 것만 쓴다

자동화 알림에 넣을 값은 사람이 기억해서 적는 게 아니라, 스크립트가 그 자리에서 뽑을 수 있어야 한다. 그래야 실패했을 때도 같은 형식으로 남는다.

Git 저장소 안에서라면 이런 값부터 확인할 수 있다.

pwd
git rev-parse --short HEAD
date +%Y-%m-%dT%H:%M:%S%z

pwd는 작업이 어느 폴더에서 돌았는지 보여준다. 은근히 중요하다. 자동화는 내가 생각한 폴더가 아니라 다른 경로에서 돌고 있는 경우가 있다.

git rev-parse --short HEAD는 현재 커밋을 짧게 찍는다. 실패가 코드 변경 때문인지, 외부 상태 때문인지 가를 때 첫 단서가 된다.

date는 실패 시각이다. 예약 작업이 새벽에 여러 번 돌면 “언제 죽었는지”가 생각보다 빨리 헷갈린다.

텔레그램에는 토큰보다 메시지 설계를 먼저 붙잡는다

텔레그램으로 보내려면 봇 토큰과 채팅방 ID가 필요하다. 이건 별도로 만들어서 환경 변수나 비밀값 저장소에 넣으면 된다. 다만 처음부터 토큰 설정에만 매달리면 정작 알림 내용이 빈약해진다.

내 경우에는 발송 성공보다 메시지 형식이 먼저였다. 알림이 와도 “실패함” 한 줄뿐이면 결국 서버에 들어가서 처음부터 다 뒤져야 한다. 그러면 알림을 붙인 의미가 별로 없다.

좋은 실패 알림은 이런 식으로 읽힌다.

아, publish 단계에서 죽었네.
현재 커밋은 66f728c네.
로그는 logs/publish.log 보면 되겠네.

이 정도면 충분하다. 텔레그램 안에서 문제를 다 해결하려고 하지 않아도 된다.

실패한 뒤에만 보내야 알림을 믿게 된다

성공 알림까지 매번 보내면 처음엔 뿌듯한데 금방 안 보게 된다. 자동화가 자주 돈다면 더 그렇다. 텔레그램 방이 초록색 성공 메시지로 차기 시작하면, 진짜 실패도 그냥 지나친다.

그래서 실패 알림만 보내는 쪽이 낫다. 성공 여부는 로그나 대시보드에서 보면 되고, 텔레그램은 사람이 봐야 할 때만 울리는 편이 좋았다.

조건은 단순하다.

상황	알림
정상 종료	보내지 않음
실패 종료	한 번만 보냄
재시도 후 성공	필요하면 마지막 상태만 보냄
같은 실패 반복	중복을 줄일 방법을 따로 둠

여기서 헷갈렸던 건 “재시도 중인 실패”였다. 한 번 실패하고 바로 재시도하는 구조라면, 첫 실패마다 알림을 보내면 너무 시끄럽다. 최종 실패가 확정됐을 때만 보내는 편이 낫다.

로그 전문은 텔레그램에 넣지 않는다

로그는 원본 위치를 남기는 게 낫다. 텔레그램 메시지에 로그를 많이 넣으면 보기에도 별로고, 줄바꿈이나 특수문자 때문에 메시지가 깨질 때도 있다.

대신 마지막 에러 한두 줄 정도만 붙이는 건 괜찮다. 다만 그것도 보조 정보다. 핵심은 “원본 로그가 어디 있는지”다.

예를 들면 이런 식이다.

에러: build step exited with code 1
로그: logs/build-2026-07-26.log

처음엔 에러 전문을 다 보내고 싶었다. 그런데 길게 보낼수록 텔레그램은 디버깅 도구가 아니라 스팸처럼 느껴졌다. 알림은 짧게, 조사는 로그에서. 이 기준이 잡히고 나서야 메시지가 덜 지저분해졌다.