windows_exporter

README

windows_exporter

A Prometheus exporter for Windows machines.

Dashboard and Alerting rules

You can find dashboards and alerting rules in the contrib directory.

Collectors

Name	Description	Enabled by default
ad	Active Directory Domain Services
adcs	Active Directory Certificate Services
adfs	Active Directory Federation Services
cache	Cache metrics
cpu	CPU usage	✓
cpu_info	CPU Information
container	Container metrics
diskdrive	Diskdrive metrics
dfsr	DFSR metrics
dhcp	DHCP Server
dmi	DMI / SMBIOS system information
dns	DNS Server
exchange	Exchange metrics
file	File metrics
fsrmquota	Microsoft File Server Resource Manager (FSRM) Quotas collector
gpu	GPU metrics
hyperv	Hyper-V hosts
iis	IIS sites and applications
license	Windows license status
logical_disk	Logical disks, disk I/O	✓
memory	Memory usage metrics	✓
mscluster	MSCluster metrics
msmq	MSMQ queues
mssql	SQL Server Performance Objects metrics
netframework	.NET Framework metrics
net	Network interface I/O	✓
nps	Network Policy Server (NPS)
os	OS information (hostname, product/version, install time)	✓
pagefile	pagefile metrics
performancecounter	Custom performance counter metrics
physical_disk	physical disk metrics	✓
printer	Printer metrics
process	Per-process metrics
registry	Windows registry values (REG_DWORD and REG_QWORD)
remote_fx	RemoteFX protocol (RDP) metrics
scheduled_task	Scheduled Tasks metrics
service	Service state metrics	✓
smb	SMB Server
smbclient	SMB Client
smtp	IIS SMTP Server
storage_spaces	Storage Spaces pools and virtual disks
system	System calls	✓
tcp	TCP connections
terminal_services	Terminal services (RDS)
textfile	Read prometheus metrics from a text file
time	Windows Time Service
udp	UDP connections
update	Windows Update Service
vmware	Performance counters installed by the Vmware Guest agent
wmi	Custom WMI query metrics

See the linked documentation on each collector for more information on reported metrics, configuration settings and usage examples.

Filtering enabled collectors

The windows_exporter will expose all metrics from enabled collectors by default. This is the recommended way to collect metrics to avoid errors when comparing metrics of different families.

For advanced use the windows_exporter can be passed an optional list of collectors to filter metrics. The collect[] parameter may be used multiple times. In Prometheus configuration you can use this syntax under the scrape config.

  params:
    collect[]:
      - foo
      - bar

This can be useful for having different Prometheus servers collect specific metrics from nodes.

Flags

windows_exporter accepts flags to configure certain behaviours. The ones configuring the global behaviour of the exporter are listed below, while collector-specific ones are documented in the respective collector documentation above.

Flag	Description	Default value
--web.listen-address	host:port for exporter.	:9182
--telemetry.path	URL path for surfacing collected metrics. Must start with /, must not be /health and, with --debug.enabled, must not be a /debug/pprof/ route.	/metrics
--collectors.enabled	Comma-separated list of collectors to use. Use [defaults] as a placeholder which gets expanded containing all the collectors enabled by default.	[defaults]
--scrape.timeout-margin	Seconds to subtract from the timeout allowed by the client. The margin takes at most half of the client's timeout. Tune to allow for overhead or high loads. Must not be negative.	0.5
--scrape.stdout	Collect metrics once and write them to stdout, then exit. Logs go to stderr unless --log.file is set. PDH rate counters cover only a short interval on the first scrape after startup.	false
--web.config.file	A web config for setting up TLS and Auth	None
--config.file	Using a config file from path	None
--log.file	Output file of log messages. One of [stdout, stderr, eventlog, <path to log file>]. When the exporter runs as a Windows service, such as one installed by the MSI, the default is eventlog.	stdout
--log.rotation.max-size	Size in megabytes at which the log file is rotated. Requires --log.file to be a path. If another process holds the file open without delete sharing, the exporter keeps writing to it and retries the rotation every minute. A moved or deleted log file is recreated within a minute.	0 (off)
--log.rotation.max-backups	Number of rotated log files to keep. 0 keeps all.	0
--log.rotation.compress	Compress rotated log files with gzip.	false

Installation

The latest release can be downloaded from the releases page.

All binaries and installation packages are signed with an self-signed certificate. The public key can be found here. Once import into the trusted root certificate store, the binaries and installation packages will be trusted.

Each release provides a .msi installer. The installer will setup the windows_exporter as a Windows service, and may create an exception in the Windows Firewall (see example below).

If the installer is run without any parameters, the exporter will run with default settings for enabled collectors, ports, etc.

The service runs as LocalSystem unless SERVICE_ACCOUNT is set. To run it as an unprivileged service account instead, see Running as a least-privilege service account.

The installer provides a configuration file to customize the exporter.

The configuration file

• is located in the same directory as the exporter executable.
• has the YAML format and is provided with the --config.file parameter.
• can be used to enable or disable collectors, set collector-specific parameters, and set global parameters.

The following parameters are available:

Name	Description
ENABLED_COLLECTORS	As the --collectors.enabled flag, provide a comma-separated list of enabled collectors
CONFIG_FILE	Use the --config.file flag to specify a config file. If empty, default config file at install dir will be used. If set, the config file must be exist before the installation is started.
LISTEN_ADDR	The IP address to bind to. Defaults to an empty string. (any local address)
LISTEN_PORT	The port to bind to. Defaults to 9182.
METRICS_PATH	The path at which to serve metrics. Defaults to /metrics
TEXTFILE_DIRS	Use the --collector.textfile.directories flag to specify one or more directories, separated by commas, where the collector should read text files containing metrics
REMOTE_ADDR	Allows setting comma separated remote IP addresses for the Windows Firewall exception (allow list). Defaults to an empty string (any remote address).
EXTRA_FLAGS	Allows passing full CLI flags. Defaults to an empty string. For --collectors.enabled and --config.file, use the specialized properties ENABLED_COLLECTORS and CONFIG_FILE
ADDLOCAL	Enables features within the windows_exporter installer. Supported values: FirewallException
REMOVE	Disables features within the windows_exporter installer. Supported values: FirewallException
APPLICATIONFOLDER	Directory to install windows_exporter. Defaults to C:\Program Files\windows_exporter
SERVICE_ACCOUNT	Account the service runs as, for example NT SERVICE\windows_exporter. Defaults to an empty string (LocalSystem). The installer does not grant the account any rights, see permissions
SERVICE_PASSWORD	Password of SERVICE_ACCOUNT. Only a user account needs one; a virtual account or a gMSA has none. The installer does not write it to its log

[!NOTE] The installer properties are always preferred over the values defined in the config file. If you prefer to configure via the config file, avoid using any of the properties listed above.

Parameters are sent to the installer via msiexec. On PowerShell, the --% should be passed before defining properties.

Example invocations:

msiexec /i <path-to-msi-file> --% ENABLED_COLLECTORS=os,iis LISTEN_PORT=5000

Example service collector with a custom query.

msiexec /i <path-to-msi-file> --% ENABLED_COLLECTORS=os,service EXTRA_FLAGS="--collector.exchange.enabled=""ADAccessProcesses"""

Define a config file.

msiexec /i <path-to-msi-file> --% CONFIG_FILE="D:\config.yaml"

Run the service as its virtual account. Grant the account its rights afterwards, see permissions.

msiexec /i <path-to-msi-file> --% SERVICE_ACCOUNT="NT SERVICE\windows_exporter"

Alternative install directory

msiexec /i <path-to-msi-file> --% ADDLOCAL=FirewallException APPLICATIONFOLDER="F:\Program Files\windows_exporter"

On some older versions of Windows, you may need to surround parameter values with double quotes to get the installation command parsing properly:

msiexec /i C:\Users\Administrator\Downloads\windows_exporter.msi --% ENABLED_COLLECTORS="ad,iis,memory,process,tcp,textfile" TEXTFILE_DIRS="C:\custom_metrics\"

To install the exporter with creating a firewall exception, use the following command:

msiexec /i <path-to-msi-file> --% ADDLOCAL=FirewallException

PowerShell versions 7.3 and above require PSNativeCommandArgumentPassing to be set to Legacy when using --% EXTRA_FLAGS:

$PSNativeCommandArgumentPassing = 'Legacy'
msiexec /i <path-to-msi-file> ENABLED_COLLECTORS=os,service --% EXTRA_FLAGS="--collector.exchange.enabled=""ADAccessProcesses"""

Docker Implementation

The windows_exporter can be run as a Docker container. The Docker image is available on

• Docker Hub: docker.io/prometheuscommunity/windows-exporter
• GitHub Container Registry: ghcr.io/prometheus-community/windows-exporter
• quay.io Registry: quay.io/prometheuscommunity/windows-exporter

Tags

The Docker image is tagged with the version of the exporter. The latest tag is also available and points to the latest release.

Kubernetes Implementation

See detailed steps to install on Windows Kubernetes here.

Prometheus rules

The Windows exporter mixin provides configurable recording rules and alerts for Prometheus, with Jsonnet generation, pint linting, and promtool tests. Dedicated alert runbooks provide Windows diagnosis and mitigation steps and are published through GitHub Pages.

Supported versions

windows_exporter supports Windows Server versions 2016 and later, and desktop Windows version 10 and 11 (21H2 or later).

There are known compatibility issues with Windows Server 2012 R2 and earlier versions.

HTTP Endpoints

windows_exporter provides the following HTTP endpoints:

• /metrics: Exposes metrics in the Prometheus text format.
• /health: Returns 200 OK when the exporter is running.
• /debug/pprof/: Exposes the pprof endpoints. Only, if --debug.enabled is set.

CPU and goroutine profiles include a collector label with the collector name, so profiles can be filtered by collector. Workers started during collector initialization inherit this label.

Using [defaults] with --collectors.enabled argument

Using [defaults] with --collectors.enabled argument which gets expanded with all default collectors.

.\windows_exporter.exe --collectors.enabled "[defaults],process,container"

This enables the additional process and container collectors on top of the defaults.

Using a configuration file

YAML configuration files can be specified with the --config.file flag. e.g. .\windows_exporter.exe --config.file=config.yml. If you are using the absolute path, make sure to quote the path, e.g. .\windows_exporter.exe --config.file="C:\Program Files\windows_exporter\config.yml"

collectors:
  enabled: cpu,net,service
collector:
  service:
    include: windows_exporter
log:
  level: warn

An example configuration file can be found here.

Configuration file notes

Configuration file values can be mixed with CLI flags. E.G.

.\windows_exporter.exe --collectors.enabled=cpu

log:
  level: debug

CLI flags enjoy a higher priority over values specified in the configuration file.

License

Under MIT