# 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__ ``` where `` is the key's [`name`](#name) and `` 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." ```