windows_exporter/internal/collector/scheduled_task/AGENTS.md

scheduled_task collector

Scrape time is spent in the Task Scheduler service. The exporter's own CPU time is small, but the Schedule service (svchost) uses about as much CPU time as the scrape takes. Measure that with the raw PercentProcessorTime of Win32_PerfRawData_PerfProc_Process for the service's PID (100 ns units), which an unprivileged user can read.

• IRegisteredTask Name and Path are answered locally from the enumerated collection. State, Enabled, LastTaskResult and NumberOfMissedRuns each make a separate RPC to the Schedule service (roughly 0.1–0.3 ms per call). ITaskFolder::GetTasks and GetFolders add one RPC per folder each. IRegisteredTaskCollection::get_Item is local, so enumerating with _NewEnum and batched IEnumVARIANT::Next saves nothing.
• Keep the serial walk. Reading folders with concurrent workers, each with its own connection, halved the scrape time but cost the Schedule service about 40% more CPU time in total with four workers. That is a bad trade on small VMs (#2643). Re-opening folders by path instead of walking the folder objects also adds a round trip per folder.
• Read only the properties that are published, apply the include/exclude filter to the path before any service read, and keep property reads conditional on whether the metric that uses them is emitted.
• folderFilter skips subfolders whose tasks the include/exclude expressions reject whatever their names are, by analyzing the parsed expressions. It must stay conservative: when in doubt, walk the folder. A Windows 11 desktop has about 150 folders for about 200 tasks, and listing the tasks and subfolders of each costs ~0.15 ms per call, so exclude=/Microsoft/.+ saves most of a scrape. The default exclude is /Microsoft/.+ for that reason; keep ConfigDefaults and the flag default in sync through defaultTaskExclude.
• taskReader carries the task and folder filters and which properties to read. NumberOfMissedRuns is only read and published with missed-runs (off by default), which saves its two RPCs per task.
• The fake native task in scheduled_task_native_test.go counts reads per vtable slot; extend those assertions when adding a property read.
• To find slow calls, time each call type over a full enumeration on a live system. Run it as SYSTEM as well as a user: unprivileged accounts see fewer tasks.
• Each task publishes 19 const metrics, and building them is most of the allocations of a scrape. collectMetrics reuses the metrics of the previous scrape through internal/metriccache while a task's path, state, last result and missed runs are unchanged. Add new inputs of a task's metrics to taskValues, or the cache returns stale series.

Measured costs and rejected approaches

Measured in October 2026 on a Windows 11 24H2 desktop (taskschd.dll 10.0.26100.5074), unprivileged: 207 tasks in 150 folders (134 leaf folders, 36 of them empty), about 150 ms per scrape without filters.

• Per call: GetTasks ~170 µs and GetFolders ~145 µs per folder; State and LastTaskResult ~130 µs per task; NumberOfMissedRuns ~310 µs per task (~560 µs for disabled tasks). Path and folder Path take 1–2 µs (local). NumberOfMissedRuns alone is about 28% of a scrape.
• NumberOfMissedRuns is computed with two RPCs: SchRpcGetLastRunInfo (opnum 16), then SchRpcScheduledRuntimes (opnum 15) from the start of the last run to the current local time with an unlimited cRequested. The service computes every scheduled run in that window from the task definition and returns all of them, so tasks with many missed runs (13,146 seen) send large responses each scrape. Tasks without time triggers return SCHED_S_TASK_NOT_SCHEDULED. LastTaskResult also calls SchRpcGetLastRunInfo, so reading both costs one duplicate round trip. SchRpcGetNumberOfMissedRuns (opnum 18) always returns 0 and is not what COM uses.
• Missed runs are rare but real: 6 of 207 tasks were non-zero, 2 of them disabled. Skipping the read for disabled tasks would change published values.
• A persistent COM connection (dedicated thread, service kept connected) saves ~1.7 ms per scrape. CoCreateInstance and Connect are cheap; the service's per-call time dominates.
• Direct MS-TSCH RPC over ncalrpc (hand-marshalled NDR, I_RpcSendReceive) is only 5–8 µs faster per call. It would only save the duplicate SchRpcGetLastRunInfo (~18 ms per scrape, ~12%) plus ~9 ms of client CPU, at the cost of a hand-written NDR client. Not worth it. Note that SchRpcGetTaskInfo only returns the state with SCH_FLAG_STATE (0x10000000).
• One SchRpcEnumInstances for all running tasks took ~21 ms, slower than the per-task state reads.
• There is no flat or recursive task enumeration: GetTasks/GetFolders and SchRpcEnumTasks/SchRpcEnumFolders list one folder each, with only the hidden-task flag. The registry TaskCache is undocumented and not readable without admin rights.
• MSFT_ScheduledTask (CIM, root/Microsoft/Windows/TaskScheduler) returns a flat list with path and state, but is about 3× slower: ~440 ms through internal/mi in-process for the same 207 tasks, whatever properties are selected, plus ~120 ms for last result and missed runs. The work moves into WmiPrvSE (up to ~30% of one core while querying).
• missed_runs is opt-in through missed-runs. Not taken yet: a cache duration that serves the last task list.
• Profiling the exporter with pprof on Windows attributes the time blocked in these COM calls to runtime.cgocall; that is waiting, not exporter CPU. The Schedule service's own CPU needs an elevated reader of its process times.