InfoGrab DocsInfoGrab Docs

Durable scheduler 소개

요약

durable scheduler는 Schedule Trigger 노드로 시작하는 것과 같은 시간 기반 워크플로를, 각 인스턴스의 메모리 대신 데이터베이스 기반 큐에서 실행합니다. durable scheduler는 n8n 2.36.0부터 제공됩니다.

durable scheduler는 Schedule Trigger 노드로 시작하는 것과 같은 시간 기반 워크플로를, 각 인스턴스의 메모리 대신 데이터베이스 기반 큐에서 실행합니다. n8n 2.45.0부터 기본적으로 켜져 있습니다. 이 페이지에서는 durable scheduler가 무엇을 변경하는지, 구성하는 방법, 인메모리 스케줄러를 사용하는 방법, 작동 방식을 설명합니다. 이를 구성하는 환경 변수는 스케줄러 환경 변수를 참고하세요.

Note

기능 제공 범위

durable scheduler는 n8n 2.36.0부터 제공됩니다. n8n 2.32.0까지의 이전 버전에는 프리뷰 기능으로 포함되어 있습니다. n8n 2.45.0 이전에는 기본적으로 꺼져 있습니다. n8n 2.45.0부터는 명시적으로 끄지 않는 한 새 인스턴스와 기존 인스턴스 모두에서 기본적으로 켜져 있습니다.

인메모리 스케줄러와 durable scheduler 비교#

인메모리 스케줄러는 n8n 2.45.0 이전의 기본값이었습니다. 활성 스케줄이 언제 실행되어야 하는지 계산하고, 해당 타이머를 main 인스턴스의 프로세스 안에 보관합니다. 이 방식은 단일 인스턴스에서는 잘 작동하지만 다음과 같은 한계가 있습니다.

  • 재시작 시 대기 중인 실행이 유실됩니다. 인스턴스가 중지되면 메모리 안의 타이머도 함께 사라집니다. n8n은 다운타임 동안 시각이 지난 실행을 나중에 따라잡지 않고 건너뜁니다.
  • 여러 인스턴스에는 리더가 필요합니다. 멀티 메인 구성에서는 리더만 스케줄을 실행합니다. 잘못된 시점에 리더십이 바뀌면 타이밍이 어긋날 수 있습니다.

durable scheduler는 스케줄링을 데이터베이스로 옮겨 이 두 가지 문제를 모두 해결합니다.

  • 재시작해도 실행이 유지됩니다. 스케줄러는 예정 시각이 되기 전에 다가오는 각 실행을 데이터베이스에 기록합니다. 재시작해도 실행이 유실되지 않습니다. 인스턴스가 중단된 동안 시각이 지난 실행도 유예 기간(grace period) 이내라면 인스턴스가 복구되었을 때 늦게라도 실행됩니다. 유예 기간을 넘기면 트리거의 미스파이어 정책이 처리 방법을 결정합니다.
  • 하나의 인스턴스가 각 실행을 확보합니다. 모든 main 인스턴스가 동일한 큐를 공유하며 그 큐에서 실행을 확보(claim)합니다. 각 실행은 한 번에 하나의 인스턴스만 보유하므로, 작업이 단일 리더에 의존하지 않고 main 인스턴스 전체에 분산됩니다.

기능적으로 달라지는 점#

n8n 2.45.0으로 업그레이드하거나 durable scheduler를 켜면 다음 동작이 적용됩니다.

  • 타이밍이 정확하게 유지됩니다. 인메모리 스케줄러와 마찬가지로, 실행은 예정된 시각에 정확히 시작됩니다.
  • n8n 2.45.0부터 고정 간격이 기본값입니다. "매 N초"와 "매 N분" 스케줄은 워크플로를 게시한 시점부터 측정한 균일한 간격으로 실행됩니다. 시계 정렬 타이밍을 유지하려면 N8N_SCHEDULER_TRIGGER_NODE_MODE=legacy를 설정하세요. Schedule Trigger 타이밍을 참고하세요.
  • 놓친 실행은 미스파이어 정책을 따릅니다. 스케줄러가 실행을 미리 기록해두기 때문에, 다운타임 중에 놓친 실행도 기록에 남습니다. 유예 기간 이내라면 늦게라도 실행되고, 유예 기간을 넘기면 트리거의 미스파이어 정책에 따라 n8n이 해당 실행을 폐기하거나 따라잡기(catch-up) 실행을 수행합니다.

Durable scheduler 구성#

n8n 2.45.0부터 N8N_SCHEDULER_ENABLED의 기본값은 true이므로 따로 설정할 필요가 없습니다. 업그레이드 전에 이 값을 false로 설정했다면, 값을 유지해 인메모리 스케줄러에 머물거나 변수를 제거하고 n8n을 재시작해 durable scheduler를 사용할 수 있습니다. n8n 2.45.0 이전에는 옵트인하려면 이 값을 true로 설정하세요.

Warning

durable scheduler는 워크플로 게시 서비스(workflow publication service)도 켜져 있을 때만 Schedule Trigger 노드를 인계받습니다. N8N_USE_WORKFLOW_PUBLICATION_SERVICE는 기본적으로 켜져 있습니다. 이를 false로 설정하면 n8n이 경고 로그를 남기고, N8N_SCHEDULER_ENABLED가 true여도 Schedule Trigger 노드는 계속 인메모리 스케줄러에서 실행됩니다.

나머지 변수는 스케줄러가 켜져 있는 동안에만 적용됩니다. 기본값은 대부분의 인스턴스에 적합하므로, 타이밍 정확도, 스토리지, 인스턴스 간 부하를 조정할 때만 값을 변경하세요. 별도로 명시하지 않는 한 모든 시간 단위는 초입니다.

인메모리 스케줄러 사용#

인메모리 스케줄링을 유지하거나 복원하려면 다음 환경 변수를 설정하고 n8n을 재시작하세요.

export N8N_SCHEDULER_ENABLED=false

이 설정은 인스턴스의 모든 Schedule Trigger 노드와 레거시 Cron 노드에 적용됩니다. 멀티 메인 구성에서는 모든 main 인스턴스에 같은 값을 사용하세요.

n8n 2.45.0은 인메모리 스케줄러와 N8N_SCHEDULER_ENABLED를 더 이상 사용되지 않는 것으로 지정합니다. 이들은 대체 수단으로 계속 사용할 수 있지만, 향후 버전에서 제거될 예정입니다. N8N_SCHEDULER_ENABLED 또는 N8N_SCHEDULER_TRIGGER_NODE_MODE를 설정하면 n8n이 시작 시 지원 중단 경고를 기록합니다. 값이 새 기본값과 같다면 해당 변수를 제거하세요.

n8n 2.45.0은 Skip Durable Scheduler 노드 설정과 N8N_ENV_FEAT_SKIP_DURABLE_SCHEDULER도 제거합니다. 기존 노드 설정은 더 이상 개별 트리거를 메모리에 유지하지 않습니다. 대신 N8N_SCHEDULER_ENABLED=false를 사용해 인스턴스 전체를 전환하세요.

폴링 트리거와 시스템 작업#

폴링 트리거(Google Sheets Trigger나 Airtable Trigger처럼 Poll Times 파라미터가 있는 트리거 노드)는 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED로 별도로 옵트인하지 않는 한 인메모리 스케줄러에 남습니다. 이 변수는 n8n 2.33.0부터 사용할 수 있습니다. 폴링 트리거 지원은 아직 100% 안정적이지 않으므로, 폴링 워크플로를 면밀히 지켜볼 준비가 되어 있지 않다면 프로덕션에서는 꺼 두세요. durable scheduler에서 폴링이 동작하는 방식과, N8N_SCHEDULER_POLL_TRIGGERS_ENABLED와 함께 켜기를 n8n이 권장하는 durable poll cursor에 대해서는 폴링 트리거를 참고하세요.

n8n의 내부 유지 관리 작업도 N8N_SCHEDULER_SYSTEM_TASKS_ENABLED로 옵트인하지 않는 한 프로세스 내부 타이머에 남습니다. 이 변수는 n8n 2.45.0부터 사용할 수 있습니다. durable scheduler에서 시스템 작업 실행을 참고하세요.

Durable scheduler 작동 방식#

다음 용어를 알아두면 환경 변수를 이해하기 쉽습니다.

  • 스케줄(Schedule): Schedule Trigger 노드의 "매 15분" 설정과 같은 반복 규칙입니다. 스케줄러는 각 스케줄을 데이터베이스에 저장합니다.
  • 실행(Run): 특정 시각에 스케줄이 한 번 발생하는 것을 말합니다. 스케줄러는 다가오는 실행을 개별 행(row)으로 미리 기록합니다.

스케줄러는 다섯 단계를 실행하며, 각 단계마다 자체 환경 변수가 있습니다.

  1. 구체화(Materialization). 스케줄러는 활성 스케줄을 스캔하여 (구체화 윈도우 내에서) 곧 다가올 실행을 기록합니다. 이는 실행이 예정 시각이 되기 전에 데이터베이스에 커밋되도록 합니다. 구체화 단계에서 확인한 실행이 이미 미스파이어 유예 기간을 지난 상태라면, 스케줄러가 그대로 기록하지 않고 해당 스케줄의 미스파이어 정책이 처리합니다.
  2. 실행(Execution). 스케줄러는 기록된 각 실행을 예정 시각보다 최대 한 번의 확인 주기 전에 확보(claim)하여 다른 인스턴스가 가져가지 못하게 하고, 예정된 시각에 워크플로를 시작합니다.
  3. 복구(Recovery). 인스턴스가 실행을 확보했지만 완료 전에 중지되면(예: 크래시 이후), reaper가 해당 실행을 해제하여 다른 인스턴스가 가져갈 수 있게 합니다.
  4. 보존(Retention). 스케줄러는 완료된 실행을 최근 이력으로 얼마간 보관한 다음, 테이블을 작게 유지하기 위해 삭제합니다.
  5. 소유자 정합성 확인(Owner reconciliation). 모든 스케줄에는 이를 만든 워크플로와 같은 소유자가 있습니다. 스케줄러는 각 소유자가 아직 존재하는지 주기적으로 확인하고, 소유자가 더 이상 존재하지 않는 스케줄을 중지합니다. 소유자 정합성 확인 환경 변수를 참고하세요.

여러 인스턴스에 걸쳐, 모든 main이 다섯 단계를 모두 실행합니다. 확보(claim) 방식 덕분에 이는 안전합니다. 각 실행을 하나의 인스턴스만 확보하므로, 모든 곳에서 루프를 실행해도 작업이 중복되지 않고 분산됩니다.

미스파이어 정책#

실행이 유예 기간(grace period)보다 늦어지면 놓친 것으로 간주합니다. 유예 기간의 기본값은 N8N_SCHEDULER_MISFIRE_GRACE(기본 1분)입니다. n8n 2.36.0부터는 해당 버전 이후에 추가된 Schedule Trigger 노드가 Missed Execution Grace Period (Seconds) 노드 옵션으로 자체 유예 기간을 설정할 수 있습니다. 노드의 유예 기간이 인스턴스에서 도출된 최솟값(N8N_SCHEDULER_EXECUTOR_INTERVAL과 N8N_SCHEDULER_MATERIALIZATION_WINDOW 기준)보다 낮으면 n8n이 그 값으로 올리고, 상한은 30일입니다.

놓친 실행과 그 뒤에 쌓인 백로그가 어떻게 처리되는지는 트리거의 미스파이어 정책에 따라 달라집니다.

  • Don't Run Missed Executions(기본값). n8n이 놓친 실행의 백로그를 모두 폐기하고, 스케줄은 다음 실행부터 재개됩니다. 놓친 실행을 늦게라도 실행하지 않는 인메모리 스케줄러의 동작과 같습니다.
  • Run the Most Recent Missed Execution. 백로그가 노드당 하나의 따라잡기 실행으로 합쳐지며, 해당 노드의 모든 트리거 규칙 중 가장 최근에 놓친 시각 기준으로 실행됩니다. 이후 스케줄이 재개됩니다.
  • Run the Most Recent Missed Execution Per Rule. 앞의 정책과 비슷하지만 각 트리거 규칙이 따로 따라잡기 때문에, 트리거 규칙이 여러 개인 노드는 규칙마다 따라잡기 실행을 한 번씩 수행할 수 있습니다.

n8n 2.36.0부터는 해당 버전 이후에 추가된 Schedule Trigger 노드가 If Execution Is Missed 노드 옵션으로 정책을 선택합니다. Schedule Trigger 노드 문서를 참고하세요. 폴링하는 트리거 노드(Google Sheets Trigger나 Airtable Trigger 등)는 항상 놓친 실행을 건너뛰며, 폴링은 다음 예정된 실행부터 재개됩니다.

어떤 정책이든 스케줄의 시계는 백로그를 건너뛰어 진행됩니다. 어떤 정책도 백로그를 실행 단위로 하나씩 재생하지 않습니다. 일회성 스케줄은 재개할 다음 실행이 없으므로, 따라잡기 정책에서는 여전히 늦게 실행되지만 건너뛰기 정책에서는 영구히 폐기됩니다.

Note

유예 기간을 정하려면 하한부터 시작하세요. N8N_SCHEDULER_MISFIRE_GRACE는 N8N_SCHEDULER_EXECUTOR_INTERVAL보다 크고 N8N_SCHEDULER_MATERIALIZATION_WINDOW 이상으로 유지해야 합니다(그렇지 않으면 n8n이 시작 시 경고합니다). 이 하한을 넘는 범위에서는, 실행이 놓친 것으로 간주되기 전까지 허용할 수 있는 가장 긴 지연 시간으로 설정하세요. 예를 들어 인스턴스에서 재시작이나 리더십 변경에 걸리는 시간이 기준이 됩니다. 기본값 기준으로는 60초 이상입니다.

Schedule Trigger 타이밍(차이점)#

durable scheduler에서는 대부분의 Schedule Trigger 스케줄이 인메모리에서와 동일한 방식으로 실행됩니다. 위에서 설명한 인스턴스 전체 차원의 변화는 그대로 적용됩니다. 놓친 실행은 미스파이어 정책을 따르고, 하나의 인스턴스가 각 실행을 확보합니다. 이에 더해, 특정 경우 두 가지 주기가 인메모리 스케줄러와 다르게 실행됩니다.

  • "매 N초"와 "매 N분". N8N_SCHEDULER_TRIGGER_NODE_MODE가 이 실행 방식을 제어합니다. 이 설정이 영향을 주는 유일한 주기입니다.
  • "매 N시간", "일", "주", "월". 이러한 주기는 어떤 모드에서든 일상적인 사용에서는 이전과 동일하게 실행됩니다. durable scheduler는 윤년, 한 해의 53번째 주, 일광 절약 시간 전환처럼 인메모리 스케줄러가 한 주기만큼 어긋날 수 있는 드문 달력 경계 사례를 더 정확하게 처리합니다.

N8N_SCHEDULER_TRIGGER_NODE_MODE에는 두 가지 값이 있습니다.

  • new(n8n 2.45.0부터 기본값): 워크플로를 게시한 시점부터, 시계 경계가 아니라 고정된 초 간격으로 실행됩니다. 예를 들어 분의 7초에 게시하면 "매 30초" 실행은 :37, 그다음 다음 분의 :07 순으로 배치됩니다. 분 경계를 넘나들어도 간격이 설정한 값 그대로 유지되므로, "매 7초"는 절대 어긋나지 않습니다.
  • legacy(n8n 2.45.0 이전의 기본값): 인메모리 스케줄러와 동일하게 시계 경계에서 실행됩니다. "매 30초"는 매 분의 :00과 :30에 실행됩니다. 이 패턴은 매 분의 시작에서 다시 시작되므로, 60으로 나누어떨어지지 않는 간격은 분 경계에서 고르지 않은 간격이 남습니다. "매 7초"는 :00, :07, :14부터 :56까지 실행된 다음 다시 :00으로 돌아가, 7초가 아닌 4초의 간격이 생깁니다.

시계 정렬 타이밍을 유지하려면 N8N_SCHEDULER_TRIGGER_NODE_MODE=legacy를 설정하세요. 이 경우 durable scheduler는 계속 켜져 있습니다. n8n 2.45.0은 legacy 모드와 이 변수를 더 이상 사용되지 않는 것으로 지정하며, 향후 버전에서 제거될 예정입니다. 이미 이 변수를 new로 설정했다면 제거해도 됩니다.

Note

N8N_SCHEDULER_TRIGGER_NODE_MODE는 "매 N초"와 "매 N분" 스케줄에만 영향을 줍니다. 원시 cron 표현식을 포함한 다른 모든 주기는 어느 값을 설정하든 동일하게 실행됩니다.

폴링 트리거#

N8N_SCHEDULER_POLL_TRIGGERS_ENABLED가 켜져 있으면, 폴링 트리거의 각 폴링 시각이 각각 별도의 durable 스케줄로 실행됩니다. 폴링은 재시작해도 유지되고, 다른 실행과 마찬가지로 인스턴스 전체에 분산됩니다. 폴링 트리거에만 해당하는 동작은 세 가지입니다.

  • 놓친 폴링은 항상 건너뜁니다. 폴링은 마지막 실행 이후의 새 항목을 모두 가져오므로, 따라잡기 폴링은 같은 조회를 반복하게 됩니다. 미스파이어 정책을 참고하세요.
  • 폴링이 가끔 두 번 실행될 수 있습니다. 스케줄러는 디스패치된 각 폴링이 최소 한 번 실행되는 것을 보장하며, 한 번만 실행되는 것은 보장하지 않습니다. 예를 들어 한 인스턴스가 멈추고 다른 인스턴스가 이어받을 때 폴링이 반복될 수 있습니다. 반복된 폴링이 항목을 누락하거나 중복하지 않도록 durable poll cursor를 켜세요.
  • 너무 오래 실행되는 폴링은 중단됩니다. n8n 2.37.0부터, N8N_SCHEDULER_POLL_TIMEOUT(기본값 45초)보다 오래 실행되는 폴링은 중단됩니다. n8n은 해당 폴링을 더 이상 기다리지 않고 아무것도 기록하지 않습니다. 커서는 그대로 유지되므로 다음 폴링이 같은 범위를 다시 조회하며 누락되는 데이터가 없습니다. 이는 응답하지 않는 서비스에서 폴링이 멈추는 상황을 방지합니다. 계속 시간 초과되는 폴링은 실패하는 것으로 간주합니다. n8n은 따라가지 못하는 서비스를 계속 두드리는 대신, 간격을 점점 늘려가며 다시 폴링합니다. 중단된 폴링이 다른 인스턴스가 해당 실행을 인계받을 때까지 계속 실행되고 있지 않도록, 시간 제한은 N8N_SCHEDULER_LEASE_DURATION보다 짧게 유지하세요. 시간 제한이 리스 기간(lease duration)에 도달하면 n8n이 시작 시 경고합니다.

Durable poll cursor#

각 폴링 트리거 노드는 커서를 유지합니다. 커서는 노드가 어디까지 읽었는지에 대한 기록으로, 각 폴링이 새 항목만 가져오게 해 줍니다. 기본적으로 n8n은 커서를 워크플로의 정적 데이터(static data)에 저장하며, 폴링으로 생성된 실행과는 별도로 저장합니다. 두 저장 사이에 인스턴스가 크래시하거나 두 인스턴스가 같은 노드를 동시에 폴링하면 커서와 실행이 어긋나, 워크플로가 항목을 건너뛰거나 두 번 처리할 수 있습니다.

n8n 2.36.0부터는 N8N_POLLER_DURABLE_CURSORS_ENABLED를 true로 설정하여 이를 방지할 수 있습니다. 그러면 n8n이 각 노드의 커서를 자체 데이터베이스 테이블에 보관하고 실행과 함께 저장하므로, 폴링 라운드는 완전히 수행되었거나 전혀 수행되지 않은 상태 둘 중 하나가 됩니다. durable scheduler에서 폴링 트리거를 실행할 때는 항상 이 설정을 켜기를 n8n은 권장합니다.

n8n 2.37.0부터는 N8N_SCHEDULER_ENABLED, N8N_SCHEDULER_POLL_TRIGGERS_ENABLED, N8N_USE_WORKFLOW_PUBLICATION_SERVICE가 모두 켜져 있을 때만 이 설정이 적용됩니다. 하나라도 꺼져 있으면 n8n이 시작 시 경고 로그를 남기고 커서는 워크플로 정적 데이터에 그대로 남습니다.

켰을 때 예상되는 동작은 다음과 같습니다.

  • 전환은 안전합니다. 노드의 다음 폴링이 현재 커서를 새 테이블로 옮기므로, 항목이 두 번 조회되거나 건너뛰어지지 않습니다.
  • n8n이 먼저 워크플로를 확인합니다(n8n 2.36만 해당). 시작 시 n8n은 모든 활성 워크플로의 게시된 버전을 스캔하여 트리거 노드 id가 중복되거나 누락된 곳이 있는지 확인합니다. 하나라도 발견하거나 워크플로를 스캔하지 못하면 durable poll cursor를 끄고, 인스턴스 전체에서 폴링 트리거를 인메모리 스케줄러에 유지하며, 영향을 받는 워크플로와 해결 방법을 명시한 오류를 로그에 남깁니다.
  • 다시 꺼도 되돌려지지 않습니다. 커서는 해당 테이블에 남으며, 다만 더 이상 실행과 함께 저장되지 않을 뿐입니다.
  • 커서 저장을 관찰할 수 있습니다. N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS로 폴링 트리거 메트릭을 켜세요.
Warning

N8N_POLLER_DURABLE_CURSORS_ENABLED는 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED와 함께 켜세요. 커서가 여전히 워크플로 정적 데이터에 있는 상태에서 durable scheduler로 폴링 트리거를 실행하면 항목이 누락되거나 중복될 위험이 있습니다.

관측성(Observability)#

durable scheduler는 /metrics 엔드포인트에서 Prometheus 메트릭을 노출하므로, 실행이 제때 시작되는지, 성공하는지, 큐가 비워지고 있는지 확인할 수 있습니다. 두 개의 환경 변수로 켭니다.

export N8N_METRICS=true
export N8N_METRICS_INCLUDE_SCHEDULER_METRICS=true

main 인스턴스만 스케줄러 메트릭을 내보냅니다. 엔드포인트 자체를 설정하려면 Prometheus 메트릭 활성화를 참고하세요. 메트릭을 차트로 보려면 Grafana로 메트릭 시각화를 참고하세요. n8n은 각 패널에 권장 조치가 포함된 즉시 사용 가능한 durable scheduler 대시보드를 제공합니다.

n8n 자체의 유지 관리 작업에는 N8N_METRICS_INCLUDE_SYSTEM_TASK_METRICS로 켜는 별도의 메트릭 집합이 있습니다. 이 메트릭 집합은 해당 작업이 durable scheduler에서 실행되든 인메모리 타이머에서 실행되든 모두 다룹니다. 시스템 작업을 참고하세요.

메트릭 이름에 쓰인 두 단어는 설명이 필요합니다. task는 스케줄러가 데이터베이스에 기록한 실행입니다. occurrence는 스케줄에서 계산해 낸 실행으로, 구체화 단계에서 기록되면 task가 됩니다. 대부분의 시계열에는 workflow:schedule-trigger 또는 workflow:poll-trigger 값을 갖는 task_type 레이블이 있어 Schedule Trigger 노드와 폴링 트리거를 구분할 수 있습니다.

큐 상태#

다음 네 개의 게이지는 큐의 스냅샷이며, 스크레이프할 때마다 새로 읽습니다. 클러스터 전체를 나타내므로 모든 main이 같은 값을 보고합니다. 집계할 때는 max나 avg를 사용하고 sum은 사용하지 마세요.

메트릭 알 수 있는 내용
n8n_scheduler_tasks_pending 대기 중인 기록된 실행의 수입니다. 보유한 스케줄 수에 따라 달라지므로 숫자 자체보다 추세를 살펴보세요.
n8n_scheduler_tasks_due 예정 시각이 이미 지났지만 아직 시작되지 않은 기록된 실행의 수입니다. 0에 가까워야 합니다.
n8n_scheduler_tasks_running 클러스터 전체의 인스턴스가 현재 확보하여 실행 중인 실행의 수입니다.
n8n_scheduler_oldest_pending_age_seconds 가장 오래된 도래 실행이 얼마나 밀려 있는지를 나타냅니다. 백로그를 가장 명확하게 보여 주는 신호로, 0은 대기 중인 도래 실행이 없다는 뜻이고 값이 계속 올라가면 스케줄러가 따라가지 못한다는 뜻입니다.

스크레이프할 때마다 데이터베이스를 한 번 조회하여 네 개의 게이지를 모두 가져옵니다. N8N_METRICS_SCHEDULER_INTERVAL(기본값 20초)이 이 조회를 캐시하므로, 스크레이프 간격이 짧아도 스케줄러가 읽는 테이블에 과도한 부하가 가지 않습니다.

실행 처리량과 실패#

카운터와 히스토그램은 각 main이 수행한 작업을 기록하므로, 클러스터 전체 합계는 main 전체에 걸쳐 합산하세요.

메트릭 유형 알 수 있는 내용
n8n_scheduler_tasks_dispatched_total Counter 스케줄러가 시작하도록 핸들러에 넘긴 실행의 수입니다. 스케줄링 처리량을 나타냅니다.
n8n_scheduler_tasks_completed_total Counter 최종 결과에 도달한 실행의 수로, success 또는 failure 값의 result 레이블로 구분됩니다. 실패 비율이 높아지면 스케줄러가 아니라 워크플로나 데이터베이스에 원인이 있는 것입니다.
n8n_scheduler_task_retries_total Counter 스케줄러가 재시도를 위해 큐에 다시 넣은 실패한 실행의 수입니다.
n8n_scheduler_tasks_reclaimed_total Counter 실행을 확보한 뒤 중지된 인스턴스로부터 reaper가 회수한 실행의 수입니다. 이 값이 늘어나면 인스턴스가 크래시하거나 실행 도중 확보를 잃고 있다는 뜻입니다.
n8n_scheduler_tasks_lease_lost_total Counter 다른 인스턴스가 이미 확보를 회수한 뒤에 끝난 실행의 수로, 같은 실행이 두 번 실행되었을 수 있습니다. task_type별로 구분됩니다. 폴링 트리거의 경우 인스턴스 간 중복 실행 신호이며, 이런 일이 발생해도 durable poll cursor가 커서를 올바르게 유지합니다.
n8n_scheduler_tasks_dead_lettered_total Counter N8N_SCHEDULER_MAX_ATTEMPTS번 시도한 뒤 n8n이 포기한 실행의 수입니다. 하나하나가 실행되지 못한 실행이므로, 증가하면 경보로 취급하세요.
n8n_scheduler_dispatch_lag_seconds Histogram 각 실행이 예정 시각이 지난 시점부터 시작될 때까지 기다린 시간입니다. 높은 백분위수를 살펴보세요. p99가 p50에서 멀어지면 큐 전체가 느려지는 것이 아니라 일부 실행이 정체되고 있다는 뜻입니다.

백그라운드 패스#

이 카운터들은 큐가 계속 진행되도록 하는 다섯 단계를 다룹니다. 특정 단계가 제 역할을 하지 못할 때 가장 유용합니다.

메트릭 유형 알 수 있는 내용
n8n_scheduler_occurrences_materialized_total Counter 스케줄러가 데이터베이스에 기록한 다가오는 실행의 수입니다. 게시된 스케줄이 있는데도 0에서 변하지 않으면 구체화가 멈춘 것입니다.
n8n_scheduler_jobs_deferred_total Counter 구체화 단계에서 계획하지 못해 다시 시도할 스케줄의 수입니다. 예를 들어 읽을 수 없는 표현식이 있는 스케줄이 해당됩니다.
n8n_scheduler_occurrences_misfired_total Counter 미스파이어 정책이 기록하지 않고 폐기한 도래 실행의 수로, task_type과 폐기한 policy별로 구분됩니다. 다운타임 이후에는 급증하는 것이 정상이며, 꾸준히 증가한다면 실행이 상시 늦게 도착한다는 뜻입니다.
n8n_scheduler_occurrences_retired_total Counter 따라잡기 실행으로 대체되어 스케줄러가 버린 기록된 실행의 수입니다.
n8n_scheduler_occurrences_missed_total Counter 확보되지 않은 채 마감 시한을 넘겨 reaper가 놓친 것으로 표시한 기록된 실행의 수입니다.
n8n_scheduler_tasks_pruned_total Counter 보존 단계에서 삭제한 완료된 실행의 수입니다. 전혀 증가하지 않으면 스케줄러 테이블이 계속 커집니다.
n8n_scheduler_jobs_quarantined_total Counter 소유자가 더 이상 존재하지 않아 소유자 정합성 확인이 중지시킨 스케줄의 수입니다. n8n 2.39.0부터 사용할 수 있습니다.
n8n_scheduler_orphaned_jobs_deleted_total Counter 소유자가 격리 유예 기간을 넘겨서도 계속 없어서 소유자 정합성 확인이 삭제한 중지된 스케줄의 수입니다. n8n 2.39.0부터 사용할 수 있습니다.
n8n_scheduler_jobs_revived_total Counter 소유자가 사실은 존재하는 것으로 확인되어 소유자 정합성 확인이 다시 재개한 중지된 스케줄의 수입니다. n8n 2.39.0부터 사용할 수 있습니다.

폴링 트리거 메트릭#

폴링 트리거에는 위의 스케줄러 메트릭과 별개로, 별도의 스위치인 N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS 뒤에 자체 메트릭 집합이 있습니다.

export N8N_METRICS=true
export N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS=true

main 인스턴스만 이를 내보냅니다. 이 메트릭은 스케줄러가 아니라 폴링 엔진 자체에서 나오므로, durable scheduler가 폴링을 디스패치하지 않는 경우에도 작동합니다. 스케줄러 카운터와 마찬가지로 각 main이 수행한 자체 폴링을 기록하므로, 클러스터 전체 합계는 main 전체에 걸쳐 합산하세요. n8n은 이 메트릭을 위한 즉시 사용 가능한 폴링 트리거 대시보드를 제공합니다.

메트릭 유형 알 수 있는 내용
n8n_poll_trigger_duration_seconds Histogram 각 폴링에 걸리는 시간으로, node_type과 status별로 구분됩니다. 시간이 갈수록 폴링이 느려지면 자체 간격에 가까워지고 있다는 뜻이며, 소요 시간이 그 간격을 넘으면 폴링이 겹치기 시작합니다.
n8n_poll_trigger_errors_total Counter 예외가 발생한 폴링의 수로, node_type과 auth, rate_limited, thrown 중 하나인 kind 레이블로 구분됩니다. auth는 자격 증명 문제를, rate_limited는 서비스가 허용하는 것보다 빠르게 폴링하고 있음을 나타냅니다.
n8n_poll_trigger_overlapping_ticks_total Counter 같은 프로세스에서 같은 노드의 이전 폴링이 아직 실행 중일 때 시작된 폴링의 수입니다. 인스턴스 간 중복은 대신 n8n_scheduler_tasks_lease_lost_total에 나타납니다.
n8n_poll_trigger_timeouts_total Counter N8N_SCHEDULER_POLL_TIMEOUT보다 오래 실행되어 durable scheduler가 중단한 폴링의 수로, node_type별로 구분됩니다. 중단된 폴링은 아무것도 기록하지 않으며 다음 폴링이 같은 범위를 다시 조회합니다. 꾸준히 증가한다면 폴링 대상 서비스의 응답이 시간 제한보다 느리다는 뜻입니다. 폴링을 중단하는 것은 durable scheduler뿐이므로, 인메모리 스케줄러에서는 0으로 유지됩니다. n8n 2.37.0부터 사용할 수 있습니다.
n8n_poll_trigger_cursor_commits_total Counter 완료된 커서 저장의 수로, operation(with_execution 또는 cursor_only)과 result별로 구분됩니다. result가 fence_rejected이면 오래된 폴링이 확보를 잃어 커서를 진행하지 못한 것으로, 보호 장치가 제 역할을 한 것입니다. result가 failure이면 저장 자체가 실패한 것입니다.
n8n_poll_trigger_cursor_commit_duration_seconds Histogram 각 커서 저장에 걸리는 시간으로, 동일한 operation과 result 레이블이 붙습니다.

두 개의 커서 메트릭은 전용 커서 테이블을 추적합니다. 노드는 durable poll cursor를 켠 뒤 첫 폴링부터 이 메트릭을 보고하기 시작합니다. 커서가 테이블에 그대로 남아 있으므로, 설정을 꺼도 계속 보고합니다.

위의 모든 이름은 기본 n8n_ 메트릭 접두사를 기준으로 합니다. N8N_METRICS_PREFIX를 설정했다면 해당 값으로 바꿔서 읽으세요.

관련 리소스#

Durable scheduler 소개

n8n v2.47
원문 보기

요약

durable scheduler는 Schedule Trigger 노드로 시작하는 것과 같은 시간 기반 워크플로를, 각 인스턴스의 메모리 대신 데이터베이스 기반 큐에서 실행합니다. durable scheduler는 n8n 2.36.0부터 제공됩니다.

durable scheduler는 Schedule Trigger 노드로 시작하는 것과 같은 시간 기반 워크플로를, 각 인스턴스의 메모리 대신 데이터베이스 기반 큐에서 실행합니다. n8n 2.45.0부터 기본적으로 켜져 있습니다. 이 페이지에서는 durable scheduler가 무엇을 변경하는지, 구성하는 방법, 인메모리 스케줄러를 사용하는 방법, 작동 방식을 설명합니다. 이를 구성하는 환경 변수는 스케줄러 환경 변수를 참고하세요.

Note

기능 제공 범위

durable scheduler는 n8n 2.36.0부터 제공됩니다. n8n 2.32.0까지의 이전 버전에는 프리뷰 기능으로 포함되어 있습니다. n8n 2.45.0 이전에는 기본적으로 꺼져 있습니다. n8n 2.45.0부터는 명시적으로 끄지 않는 한 새 인스턴스와 기존 인스턴스 모두에서 기본적으로 켜져 있습니다.

인메모리 스케줄러와 durable scheduler 비교#

인메모리 스케줄러는 n8n 2.45.0 이전의 기본값이었습니다. 활성 스케줄이 언제 실행되어야 하는지 계산하고, 해당 타이머를 main 인스턴스의 프로세스 안에 보관합니다. 이 방식은 단일 인스턴스에서는 잘 작동하지만 다음과 같은 한계가 있습니다.

  • 재시작 시 대기 중인 실행이 유실됩니다. 인스턴스가 중지되면 메모리 안의 타이머도 함께 사라집니다. n8n은 다운타임 동안 시각이 지난 실행을 나중에 따라잡지 않고 건너뜁니다.
  • 여러 인스턴스에는 리더가 필요합니다. 멀티 메인 구성에서는 리더만 스케줄을 실행합니다. 잘못된 시점에 리더십이 바뀌면 타이밍이 어긋날 수 있습니다.

durable scheduler는 스케줄링을 데이터베이스로 옮겨 이 두 가지 문제를 모두 해결합니다.

  • 재시작해도 실행이 유지됩니다. 스케줄러는 예정 시각이 되기 전에 다가오는 각 실행을 데이터베이스에 기록합니다. 재시작해도 실행이 유실되지 않습니다. 인스턴스가 중단된 동안 시각이 지난 실행도 유예 기간(grace period) 이내라면 인스턴스가 복구되었을 때 늦게라도 실행됩니다. 유예 기간을 넘기면 트리거의 미스파이어 정책이 처리 방법을 결정합니다.
  • 하나의 인스턴스가 각 실행을 확보합니다. 모든 main 인스턴스가 동일한 큐를 공유하며 그 큐에서 실행을 확보(claim)합니다. 각 실행은 한 번에 하나의 인스턴스만 보유하므로, 작업이 단일 리더에 의존하지 않고 main 인스턴스 전체에 분산됩니다.

기능적으로 달라지는 점#

n8n 2.45.0으로 업그레이드하거나 durable scheduler를 켜면 다음 동작이 적용됩니다.

  • 타이밍이 정확하게 유지됩니다. 인메모리 스케줄러와 마찬가지로, 실행은 예정된 시각에 정확히 시작됩니다.
  • n8n 2.45.0부터 고정 간격이 기본값입니다. "매 N초"와 "매 N분" 스케줄은 워크플로를 게시한 시점부터 측정한 균일한 간격으로 실행됩니다. 시계 정렬 타이밍을 유지하려면 N8N_SCHEDULER_TRIGGER_NODE_MODE=legacy를 설정하세요. Schedule Trigger 타이밍을 참고하세요.
  • 놓친 실행은 미스파이어 정책을 따릅니다. 스케줄러가 실행을 미리 기록해두기 때문에, 다운타임 중에 놓친 실행도 기록에 남습니다. 유예 기간 이내라면 늦게라도 실행되고, 유예 기간을 넘기면 트리거의 미스파이어 정책에 따라 n8n이 해당 실행을 폐기하거나 따라잡기(catch-up) 실행을 수행합니다.

Durable scheduler 구성#

n8n 2.45.0부터 N8N_SCHEDULER_ENABLED의 기본값은 true이므로 따로 설정할 필요가 없습니다. 업그레이드 전에 이 값을 false로 설정했다면, 값을 유지해 인메모리 스케줄러에 머물거나 변수를 제거하고 n8n을 재시작해 durable scheduler를 사용할 수 있습니다. n8n 2.45.0 이전에는 옵트인하려면 이 값을 true로 설정하세요.

Warning

durable scheduler는 워크플로 게시 서비스(workflow publication service)도 켜져 있을 때만 Schedule Trigger 노드를 인계받습니다. N8N_USE_WORKFLOW_PUBLICATION_SERVICE는 기본적으로 켜져 있습니다. 이를 false로 설정하면 n8n이 경고 로그를 남기고, N8N_SCHEDULER_ENABLED가 true여도 Schedule Trigger 노드는 계속 인메모리 스케줄러에서 실행됩니다.

나머지 변수는 스케줄러가 켜져 있는 동안에만 적용됩니다. 기본값은 대부분의 인스턴스에 적합하므로, 타이밍 정확도, 스토리지, 인스턴스 간 부하를 조정할 때만 값을 변경하세요. 별도로 명시하지 않는 한 모든 시간 단위는 초입니다.

인메모리 스케줄러 사용#

인메모리 스케줄링을 유지하거나 복원하려면 다음 환경 변수를 설정하고 n8n을 재시작하세요.

export N8N_SCHEDULER_ENABLED=false

이 설정은 인스턴스의 모든 Schedule Trigger 노드와 레거시 Cron 노드에 적용됩니다. 멀티 메인 구성에서는 모든 main 인스턴스에 같은 값을 사용하세요.

n8n 2.45.0은 인메모리 스케줄러와 N8N_SCHEDULER_ENABLED를 더 이상 사용되지 않는 것으로 지정합니다. 이들은 대체 수단으로 계속 사용할 수 있지만, 향후 버전에서 제거될 예정입니다. N8N_SCHEDULER_ENABLED 또는 N8N_SCHEDULER_TRIGGER_NODE_MODE를 설정하면 n8n이 시작 시 지원 중단 경고를 기록합니다. 값이 새 기본값과 같다면 해당 변수를 제거하세요.

n8n 2.45.0은 Skip Durable Scheduler 노드 설정과 N8N_ENV_FEAT_SKIP_DURABLE_SCHEDULER도 제거합니다. 기존 노드 설정은 더 이상 개별 트리거를 메모리에 유지하지 않습니다. 대신 N8N_SCHEDULER_ENABLED=false를 사용해 인스턴스 전체를 전환하세요.

폴링 트리거와 시스템 작업#

폴링 트리거(Google Sheets Trigger나 Airtable Trigger처럼 Poll Times 파라미터가 있는 트리거 노드)는 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED로 별도로 옵트인하지 않는 한 인메모리 스케줄러에 남습니다. 이 변수는 n8n 2.33.0부터 사용할 수 있습니다. 폴링 트리거 지원은 아직 100% 안정적이지 않으므로, 폴링 워크플로를 면밀히 지켜볼 준비가 되어 있지 않다면 프로덕션에서는 꺼 두세요. durable scheduler에서 폴링이 동작하는 방식과, N8N_SCHEDULER_POLL_TRIGGERS_ENABLED와 함께 켜기를 n8n이 권장하는 durable poll cursor에 대해서는 폴링 트리거를 참고하세요.

n8n의 내부 유지 관리 작업도 N8N_SCHEDULER_SYSTEM_TASKS_ENABLED로 옵트인하지 않는 한 프로세스 내부 타이머에 남습니다. 이 변수는 n8n 2.45.0부터 사용할 수 있습니다. durable scheduler에서 시스템 작업 실행을 참고하세요.

Durable scheduler 작동 방식#

다음 용어를 알아두면 환경 변수를 이해하기 쉽습니다.

  • 스케줄(Schedule): Schedule Trigger 노드의 "매 15분" 설정과 같은 반복 규칙입니다. 스케줄러는 각 스케줄을 데이터베이스에 저장합니다.
  • 실행(Run): 특정 시각에 스케줄이 한 번 발생하는 것을 말합니다. 스케줄러는 다가오는 실행을 개별 행(row)으로 미리 기록합니다.

스케줄러는 다섯 단계를 실행하며, 각 단계마다 자체 환경 변수가 있습니다.

  1. 구체화(Materialization). 스케줄러는 활성 스케줄을 스캔하여 (구체화 윈도우 내에서) 곧 다가올 실행을 기록합니다. 이는 실행이 예정 시각이 되기 전에 데이터베이스에 커밋되도록 합니다. 구체화 단계에서 확인한 실행이 이미 미스파이어 유예 기간을 지난 상태라면, 스케줄러가 그대로 기록하지 않고 해당 스케줄의 미스파이어 정책이 처리합니다.
  2. 실행(Execution). 스케줄러는 기록된 각 실행을 예정 시각보다 최대 한 번의 확인 주기 전에 확보(claim)하여 다른 인스턴스가 가져가지 못하게 하고, 예정된 시각에 워크플로를 시작합니다.
  3. 복구(Recovery). 인스턴스가 실행을 확보했지만 완료 전에 중지되면(예: 크래시 이후), reaper가 해당 실행을 해제하여 다른 인스턴스가 가져갈 수 있게 합니다.
  4. 보존(Retention). 스케줄러는 완료된 실행을 최근 이력으로 얼마간 보관한 다음, 테이블을 작게 유지하기 위해 삭제합니다.
  5. 소유자 정합성 확인(Owner reconciliation). 모든 스케줄에는 이를 만든 워크플로와 같은 소유자가 있습니다. 스케줄러는 각 소유자가 아직 존재하는지 주기적으로 확인하고, 소유자가 더 이상 존재하지 않는 스케줄을 중지합니다. 소유자 정합성 확인 환경 변수를 참고하세요.

여러 인스턴스에 걸쳐, 모든 main이 다섯 단계를 모두 실행합니다. 확보(claim) 방식 덕분에 이는 안전합니다. 각 실행을 하나의 인스턴스만 확보하므로, 모든 곳에서 루프를 실행해도 작업이 중복되지 않고 분산됩니다.

미스파이어 정책#

실행이 유예 기간(grace period)보다 늦어지면 놓친 것으로 간주합니다. 유예 기간의 기본값은 N8N_SCHEDULER_MISFIRE_GRACE(기본 1분)입니다. n8n 2.36.0부터는 해당 버전 이후에 추가된 Schedule Trigger 노드가 Missed Execution Grace Period (Seconds) 노드 옵션으로 자체 유예 기간을 설정할 수 있습니다. 노드의 유예 기간이 인스턴스에서 도출된 최솟값(N8N_SCHEDULER_EXECUTOR_INTERVAL과 N8N_SCHEDULER_MATERIALIZATION_WINDOW 기준)보다 낮으면 n8n이 그 값으로 올리고, 상한은 30일입니다.

놓친 실행과 그 뒤에 쌓인 백로그가 어떻게 처리되는지는 트리거의 미스파이어 정책에 따라 달라집니다.

  • Don't Run Missed Executions(기본값). n8n이 놓친 실행의 백로그를 모두 폐기하고, 스케줄은 다음 실행부터 재개됩니다. 놓친 실행을 늦게라도 실행하지 않는 인메모리 스케줄러의 동작과 같습니다.
  • Run the Most Recent Missed Execution. 백로그가 노드당 하나의 따라잡기 실행으로 합쳐지며, 해당 노드의 모든 트리거 규칙 중 가장 최근에 놓친 시각 기준으로 실행됩니다. 이후 스케줄이 재개됩니다.
  • Run the Most Recent Missed Execution Per Rule. 앞의 정책과 비슷하지만 각 트리거 규칙이 따로 따라잡기 때문에, 트리거 규칙이 여러 개인 노드는 규칙마다 따라잡기 실행을 한 번씩 수행할 수 있습니다.

n8n 2.36.0부터는 해당 버전 이후에 추가된 Schedule Trigger 노드가 If Execution Is Missed 노드 옵션으로 정책을 선택합니다. Schedule Trigger 노드 문서를 참고하세요. 폴링하는 트리거 노드(Google Sheets Trigger나 Airtable Trigger 등)는 항상 놓친 실행을 건너뛰며, 폴링은 다음 예정된 실행부터 재개됩니다.

어떤 정책이든 스케줄의 시계는 백로그를 건너뛰어 진행됩니다. 어떤 정책도 백로그를 실행 단위로 하나씩 재생하지 않습니다. 일회성 스케줄은 재개할 다음 실행이 없으므로, 따라잡기 정책에서는 여전히 늦게 실행되지만 건너뛰기 정책에서는 영구히 폐기됩니다.

Note

유예 기간을 정하려면 하한부터 시작하세요. N8N_SCHEDULER_MISFIRE_GRACE는 N8N_SCHEDULER_EXECUTOR_INTERVAL보다 크고 N8N_SCHEDULER_MATERIALIZATION_WINDOW 이상으로 유지해야 합니다(그렇지 않으면 n8n이 시작 시 경고합니다). 이 하한을 넘는 범위에서는, 실행이 놓친 것으로 간주되기 전까지 허용할 수 있는 가장 긴 지연 시간으로 설정하세요. 예를 들어 인스턴스에서 재시작이나 리더십 변경에 걸리는 시간이 기준이 됩니다. 기본값 기준으로는 60초 이상입니다.

Schedule Trigger 타이밍(차이점)#

durable scheduler에서는 대부분의 Schedule Trigger 스케줄이 인메모리에서와 동일한 방식으로 실행됩니다. 위에서 설명한 인스턴스 전체 차원의 변화는 그대로 적용됩니다. 놓친 실행은 미스파이어 정책을 따르고, 하나의 인스턴스가 각 실행을 확보합니다. 이에 더해, 특정 경우 두 가지 주기가 인메모리 스케줄러와 다르게 실행됩니다.

  • "매 N초"와 "매 N분". N8N_SCHEDULER_TRIGGER_NODE_MODE가 이 실행 방식을 제어합니다. 이 설정이 영향을 주는 유일한 주기입니다.
  • "매 N시간", "일", "주", "월". 이러한 주기는 어떤 모드에서든 일상적인 사용에서는 이전과 동일하게 실행됩니다. durable scheduler는 윤년, 한 해의 53번째 주, 일광 절약 시간 전환처럼 인메모리 스케줄러가 한 주기만큼 어긋날 수 있는 드문 달력 경계 사례를 더 정확하게 처리합니다.

N8N_SCHEDULER_TRIGGER_NODE_MODE에는 두 가지 값이 있습니다.

  • new(n8n 2.45.0부터 기본값): 워크플로를 게시한 시점부터, 시계 경계가 아니라 고정된 초 간격으로 실행됩니다. 예를 들어 분의 7초에 게시하면 "매 30초" 실행은 :37, 그다음 다음 분의 :07 순으로 배치됩니다. 분 경계를 넘나들어도 간격이 설정한 값 그대로 유지되므로, "매 7초"는 절대 어긋나지 않습니다.
  • legacy(n8n 2.45.0 이전의 기본값): 인메모리 스케줄러와 동일하게 시계 경계에서 실행됩니다. "매 30초"는 매 분의 :00과 :30에 실행됩니다. 이 패턴은 매 분의 시작에서 다시 시작되므로, 60으로 나누어떨어지지 않는 간격은 분 경계에서 고르지 않은 간격이 남습니다. "매 7초"는 :00, :07, :14부터 :56까지 실행된 다음 다시 :00으로 돌아가, 7초가 아닌 4초의 간격이 생깁니다.

시계 정렬 타이밍을 유지하려면 N8N_SCHEDULER_TRIGGER_NODE_MODE=legacy를 설정하세요. 이 경우 durable scheduler는 계속 켜져 있습니다. n8n 2.45.0은 legacy 모드와 이 변수를 더 이상 사용되지 않는 것으로 지정하며, 향후 버전에서 제거될 예정입니다. 이미 이 변수를 new로 설정했다면 제거해도 됩니다.

Note

N8N_SCHEDULER_TRIGGER_NODE_MODE는 "매 N초"와 "매 N분" 스케줄에만 영향을 줍니다. 원시 cron 표현식을 포함한 다른 모든 주기는 어느 값을 설정하든 동일하게 실행됩니다.

폴링 트리거#

N8N_SCHEDULER_POLL_TRIGGERS_ENABLED가 켜져 있으면, 폴링 트리거의 각 폴링 시각이 각각 별도의 durable 스케줄로 실행됩니다. 폴링은 재시작해도 유지되고, 다른 실행과 마찬가지로 인스턴스 전체에 분산됩니다. 폴링 트리거에만 해당하는 동작은 세 가지입니다.

  • 놓친 폴링은 항상 건너뜁니다. 폴링은 마지막 실행 이후의 새 항목을 모두 가져오므로, 따라잡기 폴링은 같은 조회를 반복하게 됩니다. 미스파이어 정책을 참고하세요.
  • 폴링이 가끔 두 번 실행될 수 있습니다. 스케줄러는 디스패치된 각 폴링이 최소 한 번 실행되는 것을 보장하며, 한 번만 실행되는 것은 보장하지 않습니다. 예를 들어 한 인스턴스가 멈추고 다른 인스턴스가 이어받을 때 폴링이 반복될 수 있습니다. 반복된 폴링이 항목을 누락하거나 중복하지 않도록 durable poll cursor를 켜세요.
  • 너무 오래 실행되는 폴링은 중단됩니다. n8n 2.37.0부터, N8N_SCHEDULER_POLL_TIMEOUT(기본값 45초)보다 오래 실행되는 폴링은 중단됩니다. n8n은 해당 폴링을 더 이상 기다리지 않고 아무것도 기록하지 않습니다. 커서는 그대로 유지되므로 다음 폴링이 같은 범위를 다시 조회하며 누락되는 데이터가 없습니다. 이는 응답하지 않는 서비스에서 폴링이 멈추는 상황을 방지합니다. 계속 시간 초과되는 폴링은 실패하는 것으로 간주합니다. n8n은 따라가지 못하는 서비스를 계속 두드리는 대신, 간격을 점점 늘려가며 다시 폴링합니다. 중단된 폴링이 다른 인스턴스가 해당 실행을 인계받을 때까지 계속 실행되고 있지 않도록, 시간 제한은 N8N_SCHEDULER_LEASE_DURATION보다 짧게 유지하세요. 시간 제한이 리스 기간(lease duration)에 도달하면 n8n이 시작 시 경고합니다.

Durable poll cursor#

각 폴링 트리거 노드는 커서를 유지합니다. 커서는 노드가 어디까지 읽었는지에 대한 기록으로, 각 폴링이 새 항목만 가져오게 해 줍니다. 기본적으로 n8n은 커서를 워크플로의 정적 데이터(static data)에 저장하며, 폴링으로 생성된 실행과는 별도로 저장합니다. 두 저장 사이에 인스턴스가 크래시하거나 두 인스턴스가 같은 노드를 동시에 폴링하면 커서와 실행이 어긋나, 워크플로가 항목을 건너뛰거나 두 번 처리할 수 있습니다.

n8n 2.36.0부터는 N8N_POLLER_DURABLE_CURSORS_ENABLED를 true로 설정하여 이를 방지할 수 있습니다. 그러면 n8n이 각 노드의 커서를 자체 데이터베이스 테이블에 보관하고 실행과 함께 저장하므로, 폴링 라운드는 완전히 수행되었거나 전혀 수행되지 않은 상태 둘 중 하나가 됩니다. durable scheduler에서 폴링 트리거를 실행할 때는 항상 이 설정을 켜기를 n8n은 권장합니다.

n8n 2.37.0부터는 N8N_SCHEDULER_ENABLED, N8N_SCHEDULER_POLL_TRIGGERS_ENABLED, N8N_USE_WORKFLOW_PUBLICATION_SERVICE가 모두 켜져 있을 때만 이 설정이 적용됩니다. 하나라도 꺼져 있으면 n8n이 시작 시 경고 로그를 남기고 커서는 워크플로 정적 데이터에 그대로 남습니다.

켰을 때 예상되는 동작은 다음과 같습니다.

  • 전환은 안전합니다. 노드의 다음 폴링이 현재 커서를 새 테이블로 옮기므로, 항목이 두 번 조회되거나 건너뛰어지지 않습니다.
  • n8n이 먼저 워크플로를 확인합니다(n8n 2.36만 해당). 시작 시 n8n은 모든 활성 워크플로의 게시된 버전을 스캔하여 트리거 노드 id가 중복되거나 누락된 곳이 있는지 확인합니다. 하나라도 발견하거나 워크플로를 스캔하지 못하면 durable poll cursor를 끄고, 인스턴스 전체에서 폴링 트리거를 인메모리 스케줄러에 유지하며, 영향을 받는 워크플로와 해결 방법을 명시한 오류를 로그에 남깁니다.
  • 다시 꺼도 되돌려지지 않습니다. 커서는 해당 테이블에 남으며, 다만 더 이상 실행과 함께 저장되지 않을 뿐입니다.
  • 커서 저장을 관찰할 수 있습니다. N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS로 폴링 트리거 메트릭을 켜세요.
Warning

N8N_POLLER_DURABLE_CURSORS_ENABLED는 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED와 함께 켜세요. 커서가 여전히 워크플로 정적 데이터에 있는 상태에서 durable scheduler로 폴링 트리거를 실행하면 항목이 누락되거나 중복될 위험이 있습니다.

관측성(Observability)#

durable scheduler는 /metrics 엔드포인트에서 Prometheus 메트릭을 노출하므로, 실행이 제때 시작되는지, 성공하는지, 큐가 비워지고 있는지 확인할 수 있습니다. 두 개의 환경 변수로 켭니다.

export N8N_METRICS=true
export N8N_METRICS_INCLUDE_SCHEDULER_METRICS=true

main 인스턴스만 스케줄러 메트릭을 내보냅니다. 엔드포인트 자체를 설정하려면 Prometheus 메트릭 활성화를 참고하세요. 메트릭을 차트로 보려면 Grafana로 메트릭 시각화를 참고하세요. n8n은 각 패널에 권장 조치가 포함된 즉시 사용 가능한 durable scheduler 대시보드를 제공합니다.

n8n 자체의 유지 관리 작업에는 N8N_METRICS_INCLUDE_SYSTEM_TASK_METRICS로 켜는 별도의 메트릭 집합이 있습니다. 이 메트릭 집합은 해당 작업이 durable scheduler에서 실행되든 인메모리 타이머에서 실행되든 모두 다룹니다. 시스템 작업을 참고하세요.

메트릭 이름에 쓰인 두 단어는 설명이 필요합니다. task는 스케줄러가 데이터베이스에 기록한 실행입니다. occurrence는 스케줄에서 계산해 낸 실행으로, 구체화 단계에서 기록되면 task가 됩니다. 대부분의 시계열에는 workflow:schedule-trigger 또는 workflow:poll-trigger 값을 갖는 task_type 레이블이 있어 Schedule Trigger 노드와 폴링 트리거를 구분할 수 있습니다.

큐 상태#

다음 네 개의 게이지는 큐의 스냅샷이며, 스크레이프할 때마다 새로 읽습니다. 클러스터 전체를 나타내므로 모든 main이 같은 값을 보고합니다. 집계할 때는 max나 avg를 사용하고 sum은 사용하지 마세요.

메트릭 알 수 있는 내용
n8n_scheduler_tasks_pending 대기 중인 기록된 실행의 수입니다. 보유한 스케줄 수에 따라 달라지므로 숫자 자체보다 추세를 살펴보세요.
n8n_scheduler_tasks_due 예정 시각이 이미 지났지만 아직 시작되지 않은 기록된 실행의 수입니다. 0에 가까워야 합니다.
n8n_scheduler_tasks_running 클러스터 전체의 인스턴스가 현재 확보하여 실행 중인 실행의 수입니다.
n8n_scheduler_oldest_pending_age_seconds 가장 오래된 도래 실행이 얼마나 밀려 있는지를 나타냅니다. 백로그를 가장 명확하게 보여 주는 신호로, 0은 대기 중인 도래 실행이 없다는 뜻이고 값이 계속 올라가면 스케줄러가 따라가지 못한다는 뜻입니다.

스크레이프할 때마다 데이터베이스를 한 번 조회하여 네 개의 게이지를 모두 가져옵니다. N8N_METRICS_SCHEDULER_INTERVAL(기본값 20초)이 이 조회를 캐시하므로, 스크레이프 간격이 짧아도 스케줄러가 읽는 테이블에 과도한 부하가 가지 않습니다.

실행 처리량과 실패#

카운터와 히스토그램은 각 main이 수행한 작업을 기록하므로, 클러스터 전체 합계는 main 전체에 걸쳐 합산하세요.

메트릭 유형 알 수 있는 내용
n8n_scheduler_tasks_dispatched_total Counter 스케줄러가 시작하도록 핸들러에 넘긴 실행의 수입니다. 스케줄링 처리량을 나타냅니다.
n8n_scheduler_tasks_completed_total Counter 최종 결과에 도달한 실행의 수로, success 또는 failure 값의 result 레이블로 구분됩니다. 실패 비율이 높아지면 스케줄러가 아니라 워크플로나 데이터베이스에 원인이 있는 것입니다.
n8n_scheduler_task_retries_total Counter 스케줄러가 재시도를 위해 큐에 다시 넣은 실패한 실행의 수입니다.
n8n_scheduler_tasks_reclaimed_total Counter 실행을 확보한 뒤 중지된 인스턴스로부터 reaper가 회수한 실행의 수입니다. 이 값이 늘어나면 인스턴스가 크래시하거나 실행 도중 확보를 잃고 있다는 뜻입니다.
n8n_scheduler_tasks_lease_lost_total Counter 다른 인스턴스가 이미 확보를 회수한 뒤에 끝난 실행의 수로, 같은 실행이 두 번 실행되었을 수 있습니다. task_type별로 구분됩니다. 폴링 트리거의 경우 인스턴스 간 중복 실행 신호이며, 이런 일이 발생해도 durable poll cursor가 커서를 올바르게 유지합니다.
n8n_scheduler_tasks_dead_lettered_total Counter N8N_SCHEDULER_MAX_ATTEMPTS번 시도한 뒤 n8n이 포기한 실행의 수입니다. 하나하나가 실행되지 못한 실행이므로, 증가하면 경보로 취급하세요.
n8n_scheduler_dispatch_lag_seconds Histogram 각 실행이 예정 시각이 지난 시점부터 시작될 때까지 기다린 시간입니다. 높은 백분위수를 살펴보세요. p99가 p50에서 멀어지면 큐 전체가 느려지는 것이 아니라 일부 실행이 정체되고 있다는 뜻입니다.

백그라운드 패스#

이 카운터들은 큐가 계속 진행되도록 하는 다섯 단계를 다룹니다. 특정 단계가 제 역할을 하지 못할 때 가장 유용합니다.

메트릭 유형 알 수 있는 내용
n8n_scheduler_occurrences_materialized_total Counter 스케줄러가 데이터베이스에 기록한 다가오는 실행의 수입니다. 게시된 스케줄이 있는데도 0에서 변하지 않으면 구체화가 멈춘 것입니다.
n8n_scheduler_jobs_deferred_total Counter 구체화 단계에서 계획하지 못해 다시 시도할 스케줄의 수입니다. 예를 들어 읽을 수 없는 표현식이 있는 스케줄이 해당됩니다.
n8n_scheduler_occurrences_misfired_total Counter 미스파이어 정책이 기록하지 않고 폐기한 도래 실행의 수로, task_type과 폐기한 policy별로 구분됩니다. 다운타임 이후에는 급증하는 것이 정상이며, 꾸준히 증가한다면 실행이 상시 늦게 도착한다는 뜻입니다.
n8n_scheduler_occurrences_retired_total Counter 따라잡기 실행으로 대체되어 스케줄러가 버린 기록된 실행의 수입니다.
n8n_scheduler_occurrences_missed_total Counter 확보되지 않은 채 마감 시한을 넘겨 reaper가 놓친 것으로 표시한 기록된 실행의 수입니다.
n8n_scheduler_tasks_pruned_total Counter 보존 단계에서 삭제한 완료된 실행의 수입니다. 전혀 증가하지 않으면 스케줄러 테이블이 계속 커집니다.
n8n_scheduler_jobs_quarantined_total Counter 소유자가 더 이상 존재하지 않아 소유자 정합성 확인이 중지시킨 스케줄의 수입니다. n8n 2.39.0부터 사용할 수 있습니다.
n8n_scheduler_orphaned_jobs_deleted_total Counter 소유자가 격리 유예 기간을 넘겨서도 계속 없어서 소유자 정합성 확인이 삭제한 중지된 스케줄의 수입니다. n8n 2.39.0부터 사용할 수 있습니다.
n8n_scheduler_jobs_revived_total Counter 소유자가 사실은 존재하는 것으로 확인되어 소유자 정합성 확인이 다시 재개한 중지된 스케줄의 수입니다. n8n 2.39.0부터 사용할 수 있습니다.

폴링 트리거 메트릭#

폴링 트리거에는 위의 스케줄러 메트릭과 별개로, 별도의 스위치인 N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS 뒤에 자체 메트릭 집합이 있습니다.

export N8N_METRICS=true
export N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS=true

main 인스턴스만 이를 내보냅니다. 이 메트릭은 스케줄러가 아니라 폴링 엔진 자체에서 나오므로, durable scheduler가 폴링을 디스패치하지 않는 경우에도 작동합니다. 스케줄러 카운터와 마찬가지로 각 main이 수행한 자체 폴링을 기록하므로, 클러스터 전체 합계는 main 전체에 걸쳐 합산하세요. n8n은 이 메트릭을 위한 즉시 사용 가능한 폴링 트리거 대시보드를 제공합니다.

메트릭 유형 알 수 있는 내용
n8n_poll_trigger_duration_seconds Histogram 각 폴링에 걸리는 시간으로, node_type과 status별로 구분됩니다. 시간이 갈수록 폴링이 느려지면 자체 간격에 가까워지고 있다는 뜻이며, 소요 시간이 그 간격을 넘으면 폴링이 겹치기 시작합니다.
n8n_poll_trigger_errors_total Counter 예외가 발생한 폴링의 수로, node_type과 auth, rate_limited, thrown 중 하나인 kind 레이블로 구분됩니다. auth는 자격 증명 문제를, rate_limited는 서비스가 허용하는 것보다 빠르게 폴링하고 있음을 나타냅니다.
n8n_poll_trigger_overlapping_ticks_total Counter 같은 프로세스에서 같은 노드의 이전 폴링이 아직 실행 중일 때 시작된 폴링의 수입니다. 인스턴스 간 중복은 대신 n8n_scheduler_tasks_lease_lost_total에 나타납니다.
n8n_poll_trigger_timeouts_total Counter N8N_SCHEDULER_POLL_TIMEOUT보다 오래 실행되어 durable scheduler가 중단한 폴링의 수로, node_type별로 구분됩니다. 중단된 폴링은 아무것도 기록하지 않으며 다음 폴링이 같은 범위를 다시 조회합니다. 꾸준히 증가한다면 폴링 대상 서비스의 응답이 시간 제한보다 느리다는 뜻입니다. 폴링을 중단하는 것은 durable scheduler뿐이므로, 인메모리 스케줄러에서는 0으로 유지됩니다. n8n 2.37.0부터 사용할 수 있습니다.
n8n_poll_trigger_cursor_commits_total Counter 완료된 커서 저장의 수로, operation(with_execution 또는 cursor_only)과 result별로 구분됩니다. result가 fence_rejected이면 오래된 폴링이 확보를 잃어 커서를 진행하지 못한 것으로, 보호 장치가 제 역할을 한 것입니다. result가 failure이면 저장 자체가 실패한 것입니다.
n8n_poll_trigger_cursor_commit_duration_seconds Histogram 각 커서 저장에 걸리는 시간으로, 동일한 operation과 result 레이블이 붙습니다.

두 개의 커서 메트릭은 전용 커서 테이블을 추적합니다. 노드는 durable poll cursor를 켠 뒤 첫 폴링부터 이 메트릭을 보고하기 시작합니다. 커서가 테이블에 그대로 남아 있으므로, 설정을 꺼도 계속 보고합니다.

위의 모든 이름은 기본 n8n_ 메트릭 접두사를 기준으로 합니다. N8N_METRICS_PREFIX를 설정했다면 해당 값으로 바꿔서 읽으세요.

관련 리소스#