registry: new collector for generating metrics from Windows registry entries (#2428)

Co-authored-by: Jan-Otto Kröpke <mail@jkroepke.de> Signed-off-by: Doug Luxem <doug@luxem.org> Signed-off-by: Jan-Otto Kröpke <mail@jkroepke.de>
2026-10-06 20:59:04 +02:00 · 2026-10-05 11:08:23 +02:00
parent 6e4a2c7138
commit 1d2ccf9910
10 changed files with 1221 additions and 2 deletions
@@ -0,0 +1,279 @@
+# 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.performancecounter.md) 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
+
+```yaml
+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:
+
+```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:
+
+```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](#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](#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`](#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](https://prometheus.io/docs/practices/naming/) (a `windows_`
+prefix, and a unit suffix such as `_bytes` or `_seconds` where applicable):
+
+```yaml
+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`](#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:
+
+```yaml
+- 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**
+
+```yaml
+  - 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."
+```