TECH NOTE · AUTOMATION OPS
자동화 스크립트에 로그를 왜 남겨야 하는지와, 나중에 읽을 수 있는 최소한의 로그 구조를 정리했습니다.
로그는 실패한 뒤에 읽으려고 남긴다
자동화 스크립트에 로그가 필요한 이유는 간단하다. 사람이 지켜보지 않는 동안 어디까지 갔고, 무엇을 입력으로 받았고, 어디서 멈췄는지 나중에 읽을 수 있어야 하기 때문이다. 자동화는 성공할 때보다 실패했을 때 더 말이 없어지는데, 이때 로그가 없으면 그냥 “어제는 됐는데 오늘은 안 된다”에서 시작하게 된다.
내 경우에는 처음엔 로그를 너무 거창하게 생각했다. 모니터링 시스템도 붙여야 할 것 같고, 포맷도 정해야 할 것 같고, 에러 코드도 멋있게 나눠야 할 것 같았다. 그런데 작은 자동화 스크립트에서는 그 정도까지 가기 전에, 최소한의 구조만 있어도 삽질 시간이 확 줄어든다.
최소 구조는 네 가지만 있으면 된다
나중에 읽을 로그라면 최소한 실행 단위, 단계, 결과, 에러 정보를 남겨야 한다. 이 네 가지가 없으면 로그가 있어도 거의 감상문처럼 된다. “실패함”은 남아 있는데, 무엇을 하다가 실패했는지는 다시 코드를 읽어야 한다.
| 항목 | 왜 남기는지 | 예시 |
|---|---|---|
| 실행 ID | 같은 시간대 로그를 한 덩어리로 묶으려고 | run_2026_07_26_001 |
| 단계 이름 | 어디까지 진행됐는지 보려고 | fetch_source, parse_posts, publish |
| 결과 상태 | 성공인지 실패인지 바로 가르려고 | success, failed, skipped |
| 에러 내용 | 다음에 뭘 봐야 할지 찾으려고 | timeout, missing title, auth expired |
처음엔 시간만 찍어도 충분할 줄 알았다. 그런데 여러 작업이 섞이면 시간만으로는 부족하다. 같은 분 안에 여러 자동화가 돌 수도 있고, 한 스크립트 안에서도 요청을 여러 번 보낼 수 있다. 그래서 실행 ID 같은 묶음 기준이 하나 있어야 나중에 덜 헷갈린다.
로그 한 줄은 사람이 읽을 수 있어야 한다
로그는 예쁘게 보이려고 남기는 게 아니다. 그래도 너무 자유롭게 쓰면 검색이 안 된다. 그래서 작은 스크립트라도 한 줄에 같은 모양으로 남기는 편이 낫다.
예를 들면 이런 식이다.
{"time":"2026-07-26T09:12:33+09:00","run_id":"run_2026_07_26_001","step":"fetch_source","status":"success","message":"loaded 12 draft posts"}
{"time":"2026-07-26T09:12:41+09:00","run_id":"run_2026_07_26_001","step":"publish","status":"failed","message":"missing title in draft-08.md"}여기서 핵심은 문장이 멋있는지가 아니다. run_id로 같은 실행을 묶을 수 있고, step으로 어느 단계인지 알 수 있고, status로 실패한 줄만 골라볼 수 있다는 점이다. 나중에 파일을 열었을 때 눈으로 읽어도 되고, 필요하면 도구로 걸러도 된다.
에러 로그에는 실패한 대상이 들어가야 한다
자동화 스크립트에서 제일 답답한 로그는 이런 식이다.
publish failed틀린 말은 아닌데, 도움이 거의 안 된다. 무엇을 발행하다가 실패했는지, 입력 파일이 뭔지, 외부 요청이 실패한 건지, 내 데이터가 이상한 건지 알 수 없다. 여기서 다시 코드를 열고, 변수 이름을 따라가고, 그날 입력 파일을 찾기 시작한다.
조금만 더 남기면 훨씬 낫다.
{"step":"publish","status":"failed","target":"draft-08.md","reason":"missing title"}이 정도면 바로 다음 행동이 정해진다. draft-08.md를 열어 제목을 보면 된다. 자동화 로그는 원인 분석을 끝내주는 도구라기보다, 다음에 볼 곳을 좁혀주는 표시판에 가깝다.
너무 많이 남기면 다시 못 읽는다
처음 로그를 붙일 때는 불안해서 모든 값을 다 찍고 싶어진다. 내 경우에는 요청 본문, 응답 전체, 중간 데이터까지 다 남기다가 로그 파일만 커지고 정작 실패 지점은 더 안 보이게 된 적이 있다.
작은 자동화에서는 보통 이 정도 기준이면 충분하다.
| 남긴다 | 굳이 안 남긴다 |
|---|---|
| 몇 개를 처리했는지 | 전체 원문 데이터 |
| 어떤 파일에서 실패했는지 | 파일 내용 전체 |
| 외부 요청이 성공/실패했는지 | 응답 전문 |
| 다시 실행할 때 필요한 식별자 | 민감한 토큰이나 쿠키 |
특히 인증값은 로그에 남기면 안 된다. 디버깅하려고 찍은 값이 나중에 더 큰 문제가 된다. 필요한 건 “인증이 실패했다”는 사실이지, 실제 토큰 문자열이 아니다.
파일은 실행 단위로 찾을 수 있게 둔다
로그 파일 이름도 너무 고민할 필요는 없다. 하루 단위로 쌓거나, 실행 단위로 나누면 된다. 중요한 건 나중에 “그때 그 실행”을 찾을 수 있어야 한다는 점이다.
예를 들면 이런 식으로 생각하면 된다.
logs/
2026-07-26.log
2026-07-27.log또는 실행 하나가 길고 복잡하면 이렇게 나눌 수도 있다.
logs/
run_2026_07_26_001.log
run_2026_07_26_002.log처음엔 하루 단위가 편하다. 파일이 너무 커지거나, 실행별로 추적해야 할 일이 많아지면 그때 실행 단위로 나눠도 늦지 않다.
성공 로그도 조금은 필요하다
실패만 남기면 충분할 것 같지만, 성공 로그도 없으면 애매해지는 순간이 온다. 자동화가 아무것도 안 한 건지, 했는데 결과가 없는 건지 구분이 안 된다.
예를 들어 글 발행 자동화라면 이런 정보가 도움이 된다.
{"step":"scan","status":"success","message":"found 12 drafts"}
{"step":"publish","status":"success","target":"draft-03.md"}
{"step":"publish","status":"skipped","target":"draft-04.md","reason":"already published"}skipped도 꽤 쓸모가 있다. 실패는 아닌데 왜 결과가 안 바뀌었는지 설명해준다. 자동화에서는 “안 했다”도 하나의 결과라서, 그냥 조용히 넘어가면 나중에 헷갈린다.
같이 나오는 질문
로그는 화면에만 찍어도 되나?
짧게 직접 실행하는 스크립트면 화면 출력만으로도 된다. 그런데 크론, CI, 백그라운드 작업처럼 나중에 다시 봐야 하는 자동화라면 파일로 남기는 편이 낫다.
처음부터 JSON 로그로 가야 하나?
꼭 그렇지는 않다. 다만 나중에 검색하거나 필터링할 가능성이 있으면 JSON 한 줄 로그가 편하다. 사람이 읽기에도 나쁘지 않고, 도구로 다루기도 쉽다.
로그를 얼마나 오래 보관해야 하나?
작은 개인 자동화라면 최근 며칠에서 몇 주 정도만 있어도 충분한 경우가 많다. 대신 실패가 자주 나는 스크립트라면 보관 기간보다 먼저 로그가 원인을 좁혀주고 있는지부터 보는 게 낫다.
다음에는 지금 쓰는 자동화 하나를 골라서, 실패했을 때 내가 열어볼 로그 한 줄이 실제로 남는지부터 보면 된다. 없어도 돌아가긴 하지만, 한 번 막히면 그 차이가 바로 난다.