windows_exporter/docs/collector.registry.md

registry collector

The registry collector exposes configured Windows registry values as named metrics. Only values of type REG_DWORD and REG_QWORD are supported.

Like the performancecounter collector, each registry value is mapped to its own metric: the key is a grouping container, and every value under it declares the metric name, type, and labels it is exported as.

Metric name prefix	registry
Data source	Windows Registry
Enabled by default?	No

Flags

--collector.registry.keys

Keys is a list of registry keys to collect values from. The value takes the form of a JSON array of objects. YAML is supported.

Caution

If you are using a configuration file, the value must be kept as a string.

Use a |- to keep the value as a string.

Example

collector:
  registry:
    keys: |-
      - name: windows_nt
        key: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion
        values:
          - name: CurrentMajorVersionNumber
            metric: windows_registry_windows_major_version
      - name: memory_management
        key: HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management
        values:
          - name: ClearPageFileAtShutdown

Schema

YAML:

- name: windows_nt # required, unique id for the key group
  key: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion
  values:
    - name: CurrentMajorVersionNumber # registry value name
      metric: windows_registry_windows_major_version # optional
      help: Windows major version number # optional
      type: gauge # optional
      labels: # optional
        product: windows
- name: memory_management # required
  key: HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management
  values:
    - name: ClearPageFileAtShutdown

JSON:

[
  {
    "name": "windows_nt",
    "key": "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion",
    "values": [
      {
        "name": "CurrentMajorVersionNumber",
        "metric": "windows_registry_windows_major_version",
        "help": "Windows major version number",
        "type": "gauge",
        "labels": { "product": "windows" }
      }
    ]
  },
  {
    "name": "memory_management",
    "key": "HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management",
    "values": [
      { "name": "ClearPageFileAtShutdown" }
    ]
  }
]

name

Required, unique id for the key group. It is used as the name label on windows_registry_key_success, to identify the key in logs, and to seed auto-generated metric names (see Metric naming). Each key must have a distinct name; duplicates are rejected at build time.

key

The full path of the registry key, including the hive. Both short and long hive names are accepted, case-insensitive, and forward slashes may be used instead of backslashes:

Short	Long
HKLM	HKEY_LOCAL_MACHINE
HKCU	HKEY_CURRENT_USER
HKU	HKEY_USERS
HKCR	HKEY_CLASSES_ROOT
HKCC	HKEY_CURRENT_CONFIG

Each key must be unique after normalization (compared case-insensitively). Subkeys are never recursed into. To collect values from a subkey, add it as a separate entry.

values

The list of registry values to read from the key. At least one value must be listed; the value names are matched case-insensitively.

A value name listed more than once under one key (compared case-insensitively) is rejected as a duplicate. If a value is missing at scrape time or is not a REG_DWORD/REG_QWORD, the scrape reports a failure for that key via windows_registry_key_success.

values Sub-Schema

name

The name of the registry value to collect. Required.

metric

The name of the metric to expose. Optional — if omitted, a name is generated automatically. See Metric naming for the exact rules and examples.

The combination of metric name and labels must be unique across all configured keys and values. Two values may deliberately share a metric name when their labels differ (a common way to aggregate the same measurement from several keys). A true duplicate — the same name and identical labels — is dropped and logged at scrape time.

help

The metric # HELP text. Optional — if omitted, it defaults to windows_exporter: custom registry metric.

type

The metric type. The value can be gauge or counter. If not specified, it defaults to gauge, which suits the configuration-style values typically stored in the registry.

This key is optional.

labels

Labels is a map of key-value pairs that will be added as constant labels to the metric. Two values may share the same metric name as long as their labels distinguish the resulting series.

This key is optional.

Metrics

The registry collector returns one metric per configured value, named and typed according to the configuration, plus a per-key success metric.

Name	Description	Type	Labels
user defined	Numeric value of a configured REG_DWORD or REG_QWORD value	gauge / counter	user defined
windows_registry_key_success	Whether the key could be opened and all of its configured values read (0, 1)	gauge	name

A windows_registry_key_success value of 0 means the key could not be opened or at least one configured value was missing or not a REG_DWORD/REG_QWORD; values that did read successfully are still exported.

The name label on windows_registry_key_success is the configured key name, used verbatim. Because each key must have a unique name, the success metric can never emit duplicate series.

Metric naming

Each value is exported under its own metric name. You can set it explicitly with the metric field, or let the collector generate one.

Explicit name. When metric is set, it is used verbatim. You are responsible for following the Prometheus naming conventions (a windows_ prefix, and a unit suffix such as _bytes or _seconds where applicable):

values:
  - name: CurrentMajorVersionNumber
    metric: windows_registry_windows_major_version

→ windows_registry_windows_major_version

Auto-generated name. When metric is omitted, the name is assembled as:

windows_registry_<group>_<value>

where <group> is the key's name and <value> is the registry value name. The whole string is then lowercased, every character that is not a letter or digit is replaced with _, and leading/trailing _ are trimmed.

Example:

- name: windows_nt
  key: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion
  values:
    - name: CurrentMajorVersionNumber

→ windows_registry_windows_nt_currentmajorversionnumber

Each special character is replaced individually rather than collapsed, so a value named Foo (Bar) becomes foo__bar (note the double underscore). Prefer an explicit metric for readable names over awkward value names.

Note

The group name is not a namespace override: name: cpu produces windows_registry_cpu_..., not windows_cpu_.... Use an explicit metric to control the entire name.

Example metric

For the example configuration above:

# HELP windows_registry_windows_major_version windows_exporter: custom registry metric
# TYPE windows_registry_windows_major_version gauge
windows_registry_windows_major_version{product="windows"} 10
# HELP windows_registry_memory_management_clearpagefileatshutdown windows_exporter: custom registry metric
# TYPE windows_registry_memory_management_clearpagefileatshutdown gauge
windows_registry_memory_management_clearpagefileatshutdown 0
# HELP windows_registry_key_success Whether the registry key could be read successfully.
# TYPE windows_registry_key_success gauge
windows_registry_key_success{name="windows_nt"} 1
windows_registry_key_success{name="memory_management"} 1

Notes

• REG_DWORD values are interpreted as unsigned 32-bit integers. Applications that store negative numbers in a DWORD will surface as large positive values.
• REG_QWORD values larger than 2^53 lose precision when converted to the 64-bit float used by Prometheus.

Useful queries

Alert if a registry value deviates from the expected value:

windows_registry_memory_management_clearpagefileatshutdown != 0

Alerting examples

prometheus.rules

  - alert: RegistryKeyReadFailure
    expr: windows_registry_key_success == 0
    for: 15m
    labels:
      severity: warning
    annotations:
      summary: "Registry key could not be read (instance {{ $labels.instance }})"
      description: "The registry key {{ $labels.name }} could not be read for 15 minutes."