title: NetBox: Background workers
agents: netbox
catalog: app/netbox
license: GPLv2
distribution: check_mk
description:
 Aggregated view of every RQ worker process from
 {/api/core/background-workers/}. One row per current worker in the service
 details: state ({idle}, {busy}, {started}, {suspended}), the queues it
 listens on, its uptime and its cumulative successful/failed job counters. A
 worker in a non-OK state ({suspended} by default) is marked with {(!)}/{(!!)}
 right on its own row, and named in the summary. The state mapping is
 configurable via the rule "NetBox background workers".

 This is deliberately a single, always-present service rather than one per
 worker: a worker's own name (usually {hostname.pid}) bakes in the OS process
 ID, so it gets a brand-new name on every restart of the {netbox-rq} process
 (deploy, upgrade, crash, a scheduled recycle) - a per-worker service would
 "vanish" and reappear as a new, undiscovered one every single time, which is
 inherent to how NetBox/RQ name workers and not fixable by choosing a
 different item. Aggregating sidesteps that entirely.

 The job counters are cumulative over each worker process's lifetime, so
 levels on the total failed count only make sense if you restart workers
 regularly. They are unset by default.

 NetBox restricts this endpoint to {superusers}. With a non-superuser token
 the service is still created (unlike the background-queues collector, which
 is silently not discovered) and reports "Worker overview unavailable" with
 the reason. The plain number of running workers is available without a
 superuser token via the "NetBox RQ Workers" service.

discovery:
 One service per host as soon as worker monitoring is enabled in the special
 agent rule and the agent produced the workers section - regardless of
 whether any workers are currently running or the collector could read them.
