Cron Explainer 사용법: 반복 작업 스케줄을 안전하게 확인하는 법

Cron 표현식은 0 9 * * *처럼 짧다. 짧아서 편하지만, 운영에서는 이 짧음이 자주 문제를 만든다. 몇 달 뒤에 보면 “이게 한국 시간 9시였나, 서버 시간 9시였나”, “평일만 돌려야 했나, 주말도 포함이었나” 같은 질문이 다시 생긴다.

oh-my-zhs의 Cron Explainer는 표현식을 외우는 도구라기보다, 사람이 생각한 반복 스케줄을 안전하게 시스템 표현식으로 낮추는 도구다. 먼저 패턴을 고르고, 숫자를 조정하고, 생성된 cron 표현식과 설명을 함께 확인한 뒤 복사하는 흐름으로 쓰면 된다.

이 글에서는 도구를 실제로 사용할 때 어떤 순서로 확인해야 하는지, KST와 UTC를 어떻게 기록해야 하는지, 월말·요일 같은 경계 조건에서 무엇을 조심해야 하는지 정리한다.

먼저 스케줄의 의도를 문장으로 적는다

도구를 열기 전에 바로 숫자부터 넣지 않는 편이 좋다. cron은 분, 시, 일, 월, 요일 다섯 칸으로 표현되지만, 실제 운영 의도는 보통 문장에 가깝다.

예를 들어 다음 문장들은 서로 다르다.

• 매일 오전 7시에 한국 사용자에게 알림을 보낸다.
• 평일 오전 9시에 내부 리포트를 만든다.
• 15분마다 토큰 만료 상태를 점검한다.
• 매월 1일 10시에 지난달 데이터를 정리한다.
• 매주 월요일 오전 8시에 주간 요약을 보낸다.

Cron Explainer의 첫 단계는 이 문장을 도구의 스케줄 패턴 중 하나로 바꾸는 것이다. 도구는 N분마다, 매 시 N분, 매일 시각, 평일 시각, 매주, 매월 같은 패턴을 제공한다. 이 중 가장 가까운 것을 고른 다음에 시간, 분, 요일, 일자를 조정한다.

핵심은 표현식이 아니라 의도다. 표현식은 마지막에 복사해도 늦지 않다.

패턴을 고르고 필요한 숫자만 바꾼다

Cron Explainer는 일반적인 운영 스케줄을 빠르게 만들 수 있도록 패턴 중심으로 구성되어 있다.

• N분마다: 토큰 점검, 큐 상태 점검, 짧은 폴링 작업에 적합하다.
• 매 시 N분: 매시간 정각 리포트, 로그 롤업처럼 시간 단위 작업에 맞다.
• 매일 시각: 매일 알림, 매일 백업, 매일 데이터 수집에 쓴다.
• 평일 시각: 업무일 기준 리포트나 팀 알림에 적합하다.
• 매주: 주간 요약, 정기 점검, 주간 정산 작업에 쓴다.
• 매월: 월초 정리, 월간 리포트, 정기 갱신 작업에 쓴다.

예를 들어 “평일 오전 9시 30분”이면 평일 시각을 고르고 시=9, 분=30을 입력한다. 도구는 30 9 * * 1-5 같은 표현식을 만들고, “평일 09:30에 실행”이라는 설명을 함께 보여준다.

이 설명을 꼭 같이 읽어야 한다. 숫자만 보면 맞아 보이지만, 설명이 의도한 문장과 다르면 아직 복사할 단계가 아니다.

자주 쓰는 cron 표현식은 결과와 함께 기억한다

실무에서 자주 쓰는 패턴은 정해져 있다.

• */5 * * * *: 5분마다 실행
• 0 * * * *: 매시 정각 실행
• 0 9 * * *: 매일 09:00 실행
• 0 9 * * 1-5: 월요일부터 금요일 09:00 실행
• 0 9 1 * *: 매월 1일 09:00 실행

이 정도는 외워도 된다. 하지만 외운 표현식을 그대로 붙여넣는 습관은 위험하다. 어떤 스케줄러는 다섯 칸이 아니라 여섯 칸을 요구한다. 어떤 서비스는 cron을 UTC 기준으로 저장한다. 어떤 환경은 요일 0과 7을 모두 일요일로 보지만, 어떤 문서는 한쪽만 강조한다.

따라서 복사 전에 확인할 것은 “문법이 맞는가”보다 “내가 원하는 달력과 맞는가”다. 도구에서 만든 설명, 설정 화면의 시간대, 배포 환경 문서를 같이 보는 편이 안전하다.

KST 작업은 UTC 변환 여부를 따로 기록한다

한국 표준시(KST)는 연중 UTC+9로 고정되어 있다. 이 점은 편하지만, 서버나 외부 스케줄러가 한국 시간으로 돈다는 뜻은 아니다. Vercel, GitHub Actions, 컨테이너, Linux 서버, 외부 워커는 기본 시간대가 UTC인 경우가 많다.

예를 들어 매일 오전 7시 KST에 텔레그램 알림을 보내고 싶다고 하자. KST 07:00은 UTC로 전날 22:00이다. 만약 스케줄러가 UTC 기준인데 0 7 * * *를 넣으면 한국 시간 오후 4시에 실행될 수 있다.

이런 실수를 줄이려면 설정 옆에 시간대를 같이 남긴다.

• 의도: 매일 07:00 KST 알림 발송
• 스케줄러 기준: UTC
• cron 표현식: 0 22 * * *
• 확인 메모: 한국 기준 다음 실행은 다음날 07:00이어야 함

반대로 서버가 KST로 설정되어 있다면 0 7 * * *가 맞을 수 있다. 중요한 것은 어느 표현식이 “정답”인지가 아니라, 표현식과 기준 시간대가 함께 기록되어 있는지다.

DST가 있는 지역은 “벽시계 시간”을 기준으로 생각한다

KST만 다루면 DST 문제는 거의 없다. 하지만 뉴욕, 런던, 베를린처럼 서머타임이 있는 도시의 회의나 알림을 다루면 단순한 시차 계산으로는 부족해진다.

예를 들어 “뉴욕 오전 9시마다 알림”은 “한국 시간 몇 시마다 알림”과 다르다. 뉴욕의 벽시계 09:00을 맞추려면 스케줄러가 America/New_York 같은 time zone을 지원하는지 확인해야 한다. 지원하지 않는 환경이라면 DST 전환 시점에 UTC 변환 값을 바꾸거나, 애플리케이션 코드에서 다음 실행 시각을 계산해야 한다.

Cron 하나로 모든 달력 규칙을 표현하려고 하면 위험하다. 반복 규칙이 단순하면 cron이 좋지만, 특정 국가의 휴일, DST, 영업일, 월말 보정이 들어가면 별도의 스케줄 로직이나 캘린더 데이터가 필요하다.

월말과 요일 조건은 경계 날짜를 확인한다

0 9 31 * *는 매월 31일 09:00이라는 뜻처럼 보인다. 하지만 31일이 없는 달에는 실행되지 않는다. “매월 말일”을 뜻하는 표현식으로 쓰면 안 된다. 어떤 시스템은 L 같은 확장 문법을 지원하지만, 표준 다섯 칸 cron에서는 환경마다 지원 여부가 다르다.

요일도 비슷하다. 1-5는 보통 월요일부터 금요일을 뜻하지만, 이 작업이 공휴일에도 실행되어야 하는지, 대체공휴일에는 어떻게 해야 하는지까지는 cron이 알지 못한다.

그래서 배포 전에는 다음과 같은 경계 날짜를 직접 확인한다.

• 월초와 월말
• 2월과 31일이 없는 달
• 주말 직전과 직후
• 연말과 연초
• DST 전환 주간이 있는 해외 시간대

Cron Explainer에서 표현식을 만든 뒤에도, 실제 배포 환경이 제공하는 next run preview가 있다면 반드시 함께 본다.

복사 전 체크리스트

운영 스케줄은 한 번 복사하면 오래 남는다. 복사 버튼을 누르기 전에 아래 항목을 빠르게 점검한다.

• 사람이 말한 스케줄 문장과 도구 설명이 같은가.
• 기준 시간대가 KST인지 UTC인지 명확한가.
• 서버, 호스팅, 외부 스케줄러의 기본 시간대를 확인했는가.
• 평일, 주말, 공휴일 요구사항을 구분했는가.
• 월말, 31일, 연말 같은 경계 날짜에서 의도와 맞는가.
• 작업 시간이 길어질 때 다음 실행과 겹쳐도 되는가.
• 실패 시 재시도, 알림, dry-run이 필요한 작업인가.
• 설정 파일이나 코드 주석에 의도와 시간대를 함께 남겼는가.

이 체크리스트는 문법보다 지루하지만, 실제 사고를 줄이는 데는 더 직접적이다.

관련 도구와 함께 쓰는 흐름

Cron Explainer만으로 충분한 경우도 있지만, 시간 관련 작업은 다른 도구와 같이 쓰면 더 안전하다.

• KST Timezone Converter: 해외 회의 시간, UTC/KST 변환, DST 차이를 확인할 때 쓴다.
• Timestamp Converter: 로그에 찍힌 Unix timestamp나 ISO 시간을 KST로 다시 읽을 때 쓴다.
• Webhook Request Simulator: 스케줄러가 호출할 webhook endpoint를 배포 전에 수동으로 테스트할 때 쓴다.

예를 들어 매일 07:00 KST에 webhook을 호출해야 한다면, 먼저 KST와 UTC를 변환하고, Cron Explainer에서 표현식을 만든 다음, Webhook Request Simulator로 실제 endpoint가 기대한 응답을 주는지 확인하는 식이다.

마무리

Cron은 작은 문자열이지만 알림, 백업, 리포트, 토큰 점검, 데이터 수집처럼 조용히 돌아가야 하는 운영 작업과 직접 닿아 있다. 그래서 “표현식을 빨리 만들기”보다 “의도, 시간대, 다음 실행 조건을 같이 확인하기”가 더 중요하다.

Cron Explainer를 사용할 때는 패턴을 고르고, 숫자를 바꾸고, 설명을 읽고, 시간대를 기록한 다음 복사하자. 짧은 문자열 하나를 복사하기 전의 몇 분이 새벽에 잘못 울리는 알림이나 하루 늦게 도착하는 리포트를 막아준다.