search

prometheus-community / windows_exporter

Prometheus exporter for Windows machines
MIT License
2.93k stars 703 forks source link
hacktoberfest prometheus prometheus-exporter windows wmi

readme

windows_exporter

CI Linting GitHub license Current Release GitHub Repo stars GitHub all releases Go Report Card

A Prometheus exporter for Windows machines.

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
cs "Computer System" metrics (system properties, num cpus/total memory)
container Container metrics
diskdrive Diskdrive metrics
dfsr DFSR metrics
dhcp DHCP Server
dns DNS Server
exchange Exchange metrics
filetime FileTime metrics
fsrmquota Microsoft File Server Resource Manager (FSRM) Quotas collector
hyperv Hyper-V hosts
iis IIS sites and applications
license Windows license status
logical_disk Logical disks, disk I/O ✓
logon User logon sessions
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 ✓
os OS metrics (memory, processes, users) ✓
pagefile pagefile metrics
perfdata Custom perfdata metrics
physical_disk physical disk metrics ✓
printer Printer metrics
process Per-process metrics
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
system System calls ✓
tcp TCP connections
terminal_services Terminal services (RDS)
textfile Read prometheus metrics from a text file
thermalzone Thermal information
time Windows Time Service
udp UDP connections
update Windows Update Service
vmware Performance counters installed by the Vmware Guest agent

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. /metrics
--telemetry.max-requests Maximum number of concurrent requests. 0 to disable. 5
--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]
--collectors.print If true, print available collectors and exit.
--scrape.timeout-margin Seconds to subtract from the timeout allowed by the client. Tune to allow for overhead or high loads. 0.5
--web.config.file A web config for setting up TLS and Auth None
--config.file Using a config file from path or URL None
--config.file.insecure-skip-verify Skip TLS when loading config file from URL false
--log.file Output file of log messages. One of [stdout, stderr, eventlog, \]
NOTE: The MSI installer will add a default argument to the installed service setting this to eventlog		 stderr

Installation

The latest release can be downloaded from the releases page.

Each release provides a .msi installer. The installer will setup the windows_exporter as a Windows service, as well as create an exception in the Windows Firewall.

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

The installer provides a configuration file to customize the exporter.

The configuration file

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, no config file will be set. The special value config.yaml set the path to the config.yaml at install dir
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

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="--collectors.exchange.enabled=""ADAccessProcesses"""

Define a config file.

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

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,logon,memory,process,tcp,textfile,thermalzone" 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="--collectors.exchange.enabled=""ADAccessProcesses"""

Docker Implementation

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

Tags

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

Additionally, a flavor hostprocess with -hostprocess as suffix is based on the https://github.com/microsoft/windows-host-process-containers-base-image which is designed to run as a Windows host process container. The size of that images is smaller than the default one.

Kubernetes Implementation

See detailed steps to install on Windows Kubernetes here.

Supported versions

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

Windows Server 2012 and 2012R2 are supported as best-effort only, but not guaranteed to work.

Usage

go get -u github.com/prometheus/promu
go get -u github.com/prometheus-community/windows_exporter
cd $env:GOPATH/src/github.com/prometheus-community/windows_exporter
promu build -v
.\windows_exporter.exe

The prometheus metrics will be exposed on localhost:9182

HTTP Endpoints

windows_exporter provides the following HTTP endpoints:

Examples

Enable only service collector and specify a custom query

.\windows_exporter.exe --collectors.enabled "service" --collector.service.include="windows_exporter"

Enable only process collector and specify a custom query

.\windows_exporter.exe --collectors.enabled "process" --collector.process.include="firefox.+"

When there are multiple processes with the same name, WMI represents those after the first instance as process-name#index. So to get them all, rather than just the first one, the regular expression must use .+. See process for more information.

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"

It is also possible to load the configuration from a URL. e.g. .\windows_exporter.exe --config.file="https://example.com/config.yml"

If you need to skip TLS verification, you can use the --config.file.insecure-skip-verify flag. e.g. .\windows_exporter.exe --config.file="https://example.com/config.yml" --config.file.insecure-skip-verify

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,logon

log:
  level: debug

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

License

Under MIT