Adding Scheduled Tasks Collector Proposal

[mousavian]

Scheduled Tasks Collector

Abstract

Add a new collector called scheduled_task that can be enabled to provide metrics about registered tasks configured in the Windows Task Scheduler Service.

Background

Task Scheduler is a component of Microsoft Windows that provides the ability to schedule the launch of computer programs or scripts at pre-defined times or after specified time intervals. ¹

The importance of having metrics for these scheduled tasks for the sake of monitoring and alerting particularly on production environments is undeniable.

Proposal

A new collector named scheduled_task will be added to collector directory.

This collector will utilise go-ole library as data source which uses Windows COM technology under the hood to communicate with Scheduler Service, as opposed to Windows Management Instrumentation (WMI) package. The reason for this is that:

The Win32_ScheduledJob class is internally using the AT protocol, which is bound to deprecation starting with Windows 8 and Windows Server 2012. As a first step the AT protocol is disabled by default. ²

Therefore, the collect function will initialise COM library at first using the CoInitialize³ function provided in the go-ole package.

A single object of the class associated with a Task Scheduler's CLSID will be created next by calling CreateInstance⁴.

After all the connections are initialised and established successfully, the collector will attempt to enumerate all the folders and collect all the registered tasks via GetFolders and GetTasks methods. ⁵

As each task comes with bunch of properties⁶, this is the time we have to decide which one to keep.
My suggestion is the following struct for a task:

type ScheduledTask struct {
	Path            string     // representing the path + name of the task. eg: "/my-folder/task-xyz"
	State           TaskState  // unsigned integer representing state <unknown, disabled, queued, ready, running>
	MissedRunsCount uint
	LastTaskResult  TaskResult // unsigned integer representing result
}

By having that structure for collected tasks, we then can output following metrics:

# HELP windows_scheduled_task_state The current state of a scheduled task 
# windows_scheduled_task_state gauge
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

# HELP windows_scheduled_task_last_result The result that was returned the last time the registered task was run
# TYPE windows_scheduled_task_last_result gauge
windows_scheduled_task_last_result{task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 1

# HELP windows_scheduled_task_missed_runs The number of times the registered task missed a scheduled run
# TYPE windows_scheduled_task_missed_runs gauge
windows_scheduled_task_missed_runs{task="/Microsoft/Windows/Chkdsk/SyspartRepair"} 0

The collector also should come with blacklist and whitelist flags in order to provide the flexibility of limiting monitored tasks; specially because Windows comes with bunch of default scheduled tasks that not might be useful to monitor for everyone.

As the final note, I suggest this collector should be disabled by default and gets enabled through config file.

Rationale

An alternative approach to monitor Windows Scheduled Tasks is utilising textfile collector cooperatively with a custom Powershell script.
Although this approach works, I believe having scheduled_tasks collector for this purpose is better solution as SchedulerTask Service is a built-in service of Windows.

Implementation

I will implement this myself and will raise a pull request. In fact, I have a working POC of this locally; so I just need to tidy it up based on feedbacks I receive on this proposal.

Related issues (if applicable)

There are few closed issues so far, related to this including #593 and #245.

[carlpett]

Hi @mousavian,
Thanks for the very detailed design doc! I think this looks like a good approach, and look forward to a PR :)
Do you see any issues in your testing so far with having OLE initialization in both a collector as well as the one done in the wmi library? I don't have any clear idea if this could be a problem or not, but one thing I'd expect us to need to be careful around.

[mousavian]

Thanks @carlpett,
I have not seen any issue during development or testing, but we haven't used this in production yet; so yeah it defiantly needs some thorough testing when in use with other collectors.

ps: I have updated the proposal with the list of new proposed metrics. I think these make much more sense.
I've also added blacklist and whitelist params, which can be very handy.

[github-actions]

This issue has been marked as stale because it has been open for 90 days with no activity. This thread will be automatically closed in 30 days if no further activity occurs.