windows_exporter/docs/collector.scheduled_task.md

scheduled_task collector

The scheduled_task collector exposes metrics about Windows Task Scheduler

Metric name prefix	scheduled_task
Data source	OLE
Enabled by default?	No

Flags

--collector.scheduled_task.include

If given, the path of the task needs to match the include regular expression in order for the corresponding metrics to be reported. Default: .+

E.G. --collector.scheduled_task.include="Firefox.*"

--collector.scheduled_task.exclude

If given, the path of the task needs to not match the exclude regular expression in order for the corresponding metrics to be reported. Default: /Microsoft/.+

The default excludes the tasks of Windows itself, below /Microsoft/. They are most of the tasks and folders of an installation and rarely worth alerting on. To report every task, set the flag to an empty value:

E.G. --collector.scheduled_task.exclude="", or exclude: "" below collector.scheduled_task in the configuration file. A key without a value keeps the default.

To report Windows tasks except some folders, list the folders to exclude instead. Tasks in folders that are not listed are reported, including folders that a Windows update adds:

E.G. --collector.scheduled_task.exclude="/Microsoft/Windows/(?:Defrag|Diagnosis|WindowsUpdate)/.+"

Each task folder costs the Task Scheduler service two requests per scrape. The collector does not read folders whose tasks the include and exclude expressions reject whatever their names are, such as everything below /Microsoft/ with the default. Expressions of the form /Folder/.+ or /Folder/.* (also as alternatives) are recognized for exclude, and a literal folder prefix for include. Errors reading folders that are not walked are not reported.

--collector.scheduled_task.missed-runs

If set, the collector reads and reports windows_scheduled_task_missed_runs. Reading the missed runs of a task costs the Task Scheduler service two requests per scrape, about a quarter of a scrape, and the service lists the start time of every missed run to count them. Without this flag, the dashboards show 0 missed runs and an empty table of tasks with missed runs. Default: false

Metrics

Name	Description	Type	Labels
windows_scheduled_task_last_result	Deprecated: use windows_scheduled_task_last_result_status. 1 if the last result code is zero, 0 otherwise; omitted for tasks that have never run	gauge	task
windows_scheduled_task_last_result_status	The last result status of a scheduled task, 1 if the current status, 0 otherwise	gauge	task, status
windows_scheduled_task_missed_runs	The number of times the registered task missed a scheduled run; only with --collector.scheduled_task.missed-runs	gauge	task
windows_scheduled_task_state	The current state of a scheduled task	gauge	task, state

For the values of the state and status labels, see below.

Last result

windows_scheduled_task_last_result_status uses the same enum convention as windows_service_state: every status is exported for each task, with exactly one status set to 1 and all others set to 0. The status metric is exported even when a task has never run.

Status	Result code (decimal)	Result code (hexadecimal)	Meaning
success	0	0x00000000	The task completed successfully
ready	267008	0x00041300	The task is ready to run
running	267009	0x00041301	The task is currently running
disabled	267010	0x00041302	The task is disabled
has_not_run	267011	0x00041303	The task has never run
no_more_runs	267012	0x00041304	No more runs are scheduled
not_scheduled	267013	0x00041305	Required scheduling properties are missing
terminated	267014	0x00041306	The last run was terminated by the user
no_valid_triggers	267015	0x00041307	No triggers exist or all triggers are disabled
event_trigger	267016	0x00041308	Event triggers do not have set run times
queued	267045	0x00041325	The task has been queued to run
unknown	Any other code	Any other code	The result code has no named status mapping

Application exit codes, scheduler errors, and unrecognized results are grouped under unknown. This status means the result code has no named mapping; it does not establish whether the task succeeded or failed. See Microsoft's Task Scheduler result codes for details.

Deprecated metric

windows_scheduled_task_last_result is deprecated. Use windows_scheduled_task_last_result_status to distinguish success, running, tasks that have never run, and other scheduler statuses. For example, use windows_scheduled_task_last_result_status{status="success"} == 1 to select successful results.

The deprecated metric remains available with its existing labels and values for compatibility. A running result code still produces 0, which does not necessarily mean the task failed. windows_scheduled_task_last_result and windows_scheduled_task_missed_runs are omitted when the result is has_not_run.

State

A task can be in the following states:

• disabled
• queued
• ready
• running
• unknown

Example metric

This Windows task is only reported with --collector.scheduled_task.exclude="".

windows_scheduled_task_last_result{task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 1
windows_scheduled_task_last_result_status{status="success",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 1
windows_scheduled_task_last_result_status{status="ready",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="running",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="disabled",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="has_not_run",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="no_more_runs",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="not_scheduled",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="terminated",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="no_valid_triggers",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="event_trigger",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="queued",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_last_result_status{status="unknown",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_missed_runs{task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_state{state="disabled",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 1
windows_scheduled_task_state{state="queued",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_state{state="ready",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_state{state="running",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0
windows_scheduled_task_state{state="unknown",task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0

Useful queries

Current result status for each task:

windows_scheduled_task_last_result_status == 1

Tasks that have never run:

windows_scheduled_task_last_result_status{status="has_not_run"} == 1

For dashboards still using the deprecated success/failure metric, exclude running tasks:

(windows_scheduled_task_last_result == 0)
unless on (job, instance, task)
(windows_scheduled_task_state{state="running"} == 1)

Alerting examples

This example treats unknown or terminated results as failures. An unknown status only means that the result code has no named mapping; adjust the alert selection for your task's exit-code conventions. Running tasks report the running status, so they do not match this alert.

prometheus.rules

  - alert: "WindowsScheduledTaskFailure"
    expr: 'windows_scheduled_task_last_result_status{status=~"unknown|terminated"} == 1'
    for: "1d"
    labels:
      severity: "high"
    annotations:
      summary: "Scheduled Task Failed"
      description: "Scheduled task '{{ $labels.task }}' failed for 1 day"