系统任务
系统任务是 n8n 为自身运行的周期性维护任务,例如修剪旧执行、压缩洞察数据、清理过期记录和续订许可证。它们不是工作流,不属于任何项目,也不会出现在编辑器中。当某项系统任务停止运行时,不会立即有功能失败,但数据库会不断增长,或者洞察数据会变得过时。
本页介绍系统任务的运行方式及其公开的 Prometheus 指标,以便你判断它们是否仍在运行,以及运行状况如何。
系统任务如何运行
每项系统任务都有自己的运行周期,可以是固定间隔或 cron 调度计划,并采用以下三种模式之一运行。下方指标的 mode 标签会指明任务使用哪种模式:
- 领导者计时器(
leader_timer):由领导者主实例中的计时器运行任务。领导者卸任时计时器停止,并在新的领导者上启动。实例停机期间到期的运行不会发生。 - 实例计时器(
instance_timer):任务所针对的每个进程都会运行自己的任务副本,因为该任务作用于该进程的状态。自 n8n 2.42.0 起可用。 - 持久模式(
durable):持久调度器通过数据库支持的队列运行任务。任何主实例都可以声明到期运行,重启也不会将其丢失。自 n8n 2.41.0 起可用。
在持久调度器上运行系统任务
要将系统任务迁移到持久调度器,请在每个主实例上设置以下环境变量,然后重启 n8n:
export N8N_SCHEDULER_ENABLED=true
export N8N_SCHEDULER_SYSTEM_TASKS_ENABLED=true
请为每个主实例上的这两个变量设置相同的值。只有支持持久模式的任务才会迁移,其余任务仍使用其计时器模式。
警告
请在每个主实例上运行相同的 n8n 版本。滚动部署期间,较旧的主实例可能通过领导者计时器运行任务,而较新的实例则通过持久调度器运行,因此任务可能执行两次。
持久系统任务同时也是调度器任务。持久调度器指标会通过值为 system:<task-name> 的 task_type 标签报告它,例如 system:insights-compaction。本页的系统任务指标会以相同名称涵盖所有三种模式。
可观测性
提示
功能可用性
系统任务指标自 n8n 2.41.0 起可用。
使用以下两个环境变量启用指标:
export N8N_METRICS=true
export N8N_METRICS_INCLUDE_SYSTEM_TASK_METRICS=true
工作线程和 webhook 处理器也会为各自的实例计时器任务公开这些指标。有关如何设置端点,请参阅启用 Prometheus 指标。有关如何绘制指标图表,请参阅使用 Grafana 可视化指标。n8n 发布了现成的系统任务仪表板,并为每个面板提供建议操作。
下方所有名称都假定使用默认的 n8n_ 指标前缀。如果设置了 N8N_METRICS_PREFIX,请替换为自己的前缀。
标签
每个序列都带有一小组固定标签:
| 标签 | 值 | 含义 |
|---|---|---|
task |
任务名称,例如 execution-pruning-soft-delete、insights-compaction 或 license-renewal |
该序列描述的系统任务。具体有哪些任务取决于 n8n 版本、许可证和设置,因此应从 n8n_system_task_info 读取列表,而不是硬编码。 |
mode |
leader_timer、instance_timer、durable |
任务在哪里运行。请参阅系统任务如何运行。在 n8n 2.42.0 之前,leader_timer 名为 in_memory。 |
result |
success、failure、aborted、lease_lost、timed_out |
一次运行的结束方式。aborted 表示实例不再担任领导者或关闭时,该运行仍在进行,因此在完成工作前停止。自 n8n 2.44.0 起,lease_lost 和 timed_out 分别表示持久运行失去声明或超过超时时间。 |
reason |
overlap、provisioned_elsewhere、aborted、coalesced |
某次发生为何未运行。请参阅内存调度。 |
这里没有实例标签。Prometheus 会为每个抓取目标添加 instance 和 job,因此对于描述任务的仪表,请使用 max by (task) 聚合;对于计数器、直方图和正在运行仪表,请使用 sum by (task)。
运行健康状况
以下三个序列涵盖所有三种模式下的运行本身。
| 指标 | 类型 | 含义 |
|---|---|---|
n8n_system_task_run_duration_seconds |
Histogram | 每次运行的持续时间,按 task、mode 和 result 区分。_count 序列同时可用作运行次数和失败次数,因此无需单独的计数器。持续时间逐渐接近任务自身的运行周期,表示 n8n 即将因运行重叠而跳过下一次发生。 |
n8n_system_task_last_success_timestamp_seconds |
Gauge | 该任务在此实例上最后一次成功运行的 Unix 时间戳。这是判断「任务是否已停止」最明确的信号,因为它也能反映从未运行过的任务,而基于计数器计算的速率无法做到这一点。 |
n8n_system_task_runs_in_flight |
Gauge | 当前在此实例上运行的该任务数量,正常情况下为 0 或 1。如果值一直为 1,表示运行已挂起;这还会阻止实例卸任或关闭。 |
调度健康状况
这些序列描述调度计划而非单次运行,因此会在首次运行发生前就存在。
| 指标 | 类型 | 含义 |
|---|---|---|
n8n_system_task_info |
Gauge | 始终为 1;此实例可运行的每项任务各有一个序列,并带有对应的 mode。这是系统任务清单,可与其联接以找出没有报告任何运行的任务。 |
n8n_system_task_interval_seconds |
Gauge | 对于按固定间隔运行的任务,表示任务声明的运行周期。这可将「延迟」转化为查询,而无需手动维护阈值列表。使用 cron 调度计划的任务不会报告此指标。 |
n8n_system_task_next_run_timestamp_seconds |
Gauge | 下一次发生的 Unix 时间戳,适用于固定间隔和 cron 调度计划。对于计时器任务,它表示此实例上的计时器已准备触发的下一次发生。时间戳停留在过去表示计时器已停止规划。对于持久任务,它表示调度器尚未规划的首次发生,因此已经规划的运行可能会更早开始。每个主实例都会报告从数据库读取的相同值。 |
n8n_system_task_scheduled |
Gauge | n8n 已调度该任务时为 1;如果任务失去调度计划(n8n 无法规划计时器运行周期,或没有可运行的持久作业),则为 0。此处为 0 表示任务已停止,而不是单纯延迟:需要重启实例(领导者计时器任务也可通过领导者变更)才能重新调度。应对此设置警报。 |
n8n_system_task_provision_check_failures_total |
Counter | n8n 无法检查任务的持久作业是否存在、因而改用领导者计时器运行任务的次数。计数上升表示数据库有问题,而且在两条路径同时生效时,存在同一任务重复运行的小幅风险。 |
持久任务或实例计时器任务的序列会在 n8n 启动时分派任务后立即出现,因此重启表现为重置,而不是数据间断。领导者计时器任务的 info、scheduled、runs_in_flight、last_success 和 next_run_timestamp_seconds 序列仅在此实例担任领导者期间存在;实例卸任时,n8n 会将它们移除:前领导者不会继续为不再执行的运行公开冻结值。只有 interval_seconds 会保留,因为运行周期不取决于由谁担任领导者。
内存调度
这些序列只涵盖计时器运行。持久路径在持久调度器指标中有对应指标:n8n_scheduler_task_retries_total 表示重试,n8n_scheduler_dispatch_lag_seconds 表示延迟。
| 指标 | 类型 | 含义 |
|---|---|---|
n8n_system_task_runs_skipped_total |
Counter | 未运行的发生次数,按 reason 区分。overlap 表示上一次运行仍在进行。provisioned_elsewhere 表示任务已有持久作业,因此领导者计时器已停用。aborted 表示发生触发时,实例已经开始卸任。coalesced 表示进程在多次发生期间处于休眠状态,计时器只为整批发生触发一次,因此计数器会按该次触发所代表的发生次数增长。 |
n8n_system_task_retries_total |
Counter | 运行失败后 n8n 调度的重试次数。只有声明了重试延迟的任务才会重试,因此任务失败而此处计数不变并不表示存在错误。 |
n8n_system_task_fire_lag_seconds |
Histogram | 每个计时器触发的延迟秒数。较小的值表示事件循环繁忙;较大的值表示进程曾暂停或休眠。其分桶范围延伸到一天,因为合并触发至少会延迟一个完整运行周期。 |