> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Windows

> Windows Event Log records, service-state metrics, and user-selected performance counters for Windows hosts, with per-channel, Service Control Manager, and per-counter-object target health.

The Windows integration requires CXDOT Collector 1.3.0 or greater.

[Windows Server](https://www.microsoft.com/en-us/windows-server) is Microsoft's
server operating system. Use the Windows integration to collect Windows Event Log
records, Windows service states, and selected performance counters from Windows
hosts.

The Windows integration supports Windows Server 2022 or greater.

## Supported telemetry types

The Windows integration supports these telemetry types:

|   Type  | Supported |
| :-----: | :-------: |
|   Logs  |    Yes    |
| Metrics |    Yes    |
|  Traces |     No    |
|  Events |     No    |

## Prerequisites

The Windows integration has the following prerequisites:

* Run the Collector directly on each Windows host with `mode: host`.
* To collect the Security channel from a Collector that runs under an account other
  than Local System, add that account to the Event Log Readers group.

## Configure

The Windows integration runs by default on Windows hosts. It collects Critical,
Error, and Warning records from the System and Application channels and the states
of a default set of Windows services. Performance counter collection is off by
default.

To configure the Windows integration, follow these steps:

1. Run the Collector in host mode. The default configuration requires no `windows`
   block. For example, add the following to the Collector configuration file:

   ```yaml theme={null}
   cxdot:
     mode: host
   ```

2. Optional: Select the Event Log channels to collect. The `channels` list replaces
   the default System and Application list, so include those channels to continue
   collecting them. For example, to add Security to the default channels, add the
   following to the Collector configuration file:

   ```yaml theme={null}
   cxdot:
     mode: host
     integrations:
       windows:
         event_logs:
           channels:
             - channel: System
             - channel: Application
               query: >-
                 <QueryList><Query Id="0" Path="Application"><Select
                 Path="Application">*[System[(Level=1 or Level=2 or
                 Level=3)]]</Select></Query></QueryList>
             - channel: Security
   ```

   Set a channel's `query` to a structured XML query to replace its default severity
   filter. The Application entry in the preceding example shows the query syntax
   while retaining the default severity filter. To reduce collection volume, use a
   query instead of filtering records after the Collector reads them.

3. Optional: Select the services to monitor. Use exact Service Control Manager
   service names, including capitalization. Run `Get-Service` in PowerShell to find
   the service names on the host. For example, add the following to the Collector
   configuration file:

   ```yaml theme={null}
   cxdot:
     mode: host
     integrations:
       windows:
         services:
           include:
             - EventLog
             - W32Time
             - MyCustomService
   ```

   Set `include` to `[all]` to monitor every installed service. This setting creates
   one time series per service, which can result in hundreds of time series per
   host. Per-user services can increase that number.

4. Optional: Configure Windows performance counters. Performance counter collection
   uses the Windows Performance Data Helper (PDH) and the English object and counter
   names shown in Performance Monitor. For example, add the following to the Collector
   configuration file:

   ```yaml theme={null}
   cxdot:
     mode: host
     integrations:
       windows:
         performance_counters:
           enabled: true
           perfcounters:
             - object: Memory
               counters:
                 - name: Committed Bytes
                   metric: windows.memory.committed
           metrics:
             windows.memory.committed:
               description: Committed virtual memory.
               unit: By
               gauge: {}
   ```

   Use `_Total` for a bounded aggregate when an object has multiple instances.
   The `*` instance selector creates one time series for every matching instance
   and excludes the `_Total` instance.

5. Optional: Disable the integration, or one of its capabilities, to stop collecting
   from a host. For example, add the following to the Collector configuration file to
   stop collecting Windows service states while continuing to collect Event Log records:

   ```yaml theme={null}
   cxdot:
     mode: host
     integrations:
       windows:
         services:
           enabled: false
   ```

   Set `enabled: false` directly under `windows` to disable the whole integration.

### Validate

To validate the Windows integration, follow these steps:

1. In Live Telemetry Analyzer, filter for
   `__name__=cxdot.integration.target.health cxdot.integration.name=windows`.
   Confirm that each configured target reports `1`. Use the
   `cxdot.integration.check` and `cxdot.integration.target` attributes to identify
   the capability and target for each result.

2. In Metrics Explorer, run the following query:

   ```text theme={null}
   {"windows.service.status", "name"="EventLog"}
   ```

   Confirm that the query returns a time series for the Windows Event Log service.
   A value of `4` means the service is running.

3. In Logs Explorer, filter for `cxdot.integration.name=windows`. Confirm that an
   Error, Warning, or Critical record written after the Collector started
   appears with its channel, event ID, message, and provider.

4. Optional: If you configured performance counters, query one of the metric names
   you defined. For the preceding example, run the following query in Metrics
   Explorer:

   ```text theme={null}
   {"windows.memory.committed"}
   ```

   Confirm that the query returns a value from each configured Windows host.

### Troubleshooting

* **A channel reports health `0`**: Confirm the channel name and structured XML
  query in Event Viewer. Confirm that the Windows account running the Collector
  can read the channel. The Security channel requires membership in the Event Log
  Readers group.
* **A channel reports health `1`, but no records appear**: The integration collects
  only records written after the Collector starts. Without a custom query, it
  collects only Critical, Error, and Warning records.
* **A configured service has no status time series**: Confirm that `services.include`
  contains the exact Service Control Manager service name with matching
  capitalization. A name that doesn't match an installed service produces no time
  series.
* **A stopped service has healthy Service Control Manager target health**: Target
  health reports whether the Collector can query the Service Control Manager.
  The `windows.service.status` metric reports the state of each service.
* **A performance counter object reports health `0`**: Confirm the English object,
  counter, and instance names in Performance Monitor. Also confirm that each
  counter's `metric` value matches a key under `metrics`. If the counter was
  unavailable when the Collector started, restart the Collector after the counter
  becomes available.
* **A performance counter object reports health `1`, but a wildcard emits no time
  series**: The counter exists, but the object currently has no instances that match
  `*`. Configure a named instance or wait for a matching instance to exist.
* **The `_Total` time series is missing from wildcard collection**: The `*` selector
  excludes `_Total`. Add a separate performance counter entry that selects only
  `_Total` and maps it to its own metric.

For more information about diagnosing a failing integration, see
[Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/troubleshooting).

## Configuration reference

Configure one Windows integration instance with the following settings. In Helm values, place
these settings under `config.integrations.windows`. In a Collector configuration file, place
them under `cxdot.integrations.windows`.

### Optional settings

* **`enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this configuration block. If true, the Collector runs the integration or
  capability. If false, the Collector doesn't run it.

* **`collection_interval`**
  Type: `duration`. Optional. Default: `60s`.
  How often the Collector reads service states and performance counters, and how often it checks
  target health. Event Log channels are polled on `event_logs.poll_interval` instead.

* **`timeout`**
  Type: `duration`. Optional. Default: `60s`.
  Time limit for each service-state or performance-counter collection and each target health
  evaluation. Windows Event Log and Performance Data Helper (PDH) calls can't be interrupted
  after they begin, so a call already in progress can outlive this timeout. A performance
  counter health evaluation stops before starting its next counter after the timeout.

* **`event_logs`**
  Type: `object`. Optional.
  Settings for collecting Windows Event Log records as log telemetry.

* **`event_logs.enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this configuration block. If true, the Collector runs the integration or
  capability. If false, the Collector doesn't run it.

* **`event_logs.channels`**
  Type: `array of object`. Optional. Default:
  `[{"channel":"System"},{"channel":"Application"}]`. Minimum items: `1`.
  Event Log channels to collect, one collection stream per entry. The default collects the
  System and Application channels, filtered to Critical, Error, and Warning events. Security is
  deliberately not a default: its volume can be far higher, especially with logon and logoff
  auditing enabled, and reading it might require the account that runs the Collector to be a
  member of the Event Log Readers group. Add it here explicitly to collect it.

* **`event_logs.channels[].channel`**
  Type: `string`. Required. Minimum length: `1`.
  Channel name as shown in Event Viewer, for example, System, Application, Security, or a
  provider channel such as Microsoft-Windows-Sysmon/Operational.

* **`event_logs.channels[].query`**
  Type: `string`. Optional. Minimum length: `1`.
  Structured XML event query, in the format that Event Viewer produces in the XML tab of Filter
  Current Log. The query replaces the default severity filter for this channel and names its own
  channel path, so it must repeat the channel. For example, `<QueryList><Query Id="0"
  Path="System"><Select Path="System">*</Select></Query></QueryList>` collects every System
  event. When unset, the channel collects Critical, Error, and Warning events.

* **`event_logs.channels[].exclude_providers`**
  Type: `array of string`. Optional.
  Event providers to drop after reading, for a provider that's noisy or can't render. Prefer
  narrowing `query`, because provider exclusion still pays the cost of reading each event. The
  cxdot-collector service provider is always excluded to prevent the Collector from ingesting
  its own error logs.

* **`event_logs.poll_interval`**
  Type: `duration`. Optional. Default: `1s`.
  How often each channel is polled for new records. Polling reads only records written since the
  previous poll, so a longer interval batches reads rather than dropping events.

* **`event_logs.max_reads`**
  Type: `integer`. Optional. Default: `100`. Minimum: `1`. Maximum: `1000`.
  Maximum records read into memory in one batch. Each poll continues reading batches until no
  records remain, so this setting doesn't cap the number of records collected per poll.

* **`services`**
  Type: `object`. Optional.
  Settings for collecting Windows service states, one `windows.service.status` time series per
  service.

* **`services.enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this configuration block. If true, the Collector runs the integration or
  capability. If false, the Collector doesn't run it.

* **`services.include`**
  Type: `array of string`. Optional. Default:
  `["CryptSvc","Dhcp","Dnscache","EventLog","LanmanServer","LanmanWorkstation","RpcSs","Schedule","WinRM"]`.
  Minimum items: `1`.
  Exact service names (the SCM name, for example, EventLog, not the display name) whose state to
  collect, one `windows.service.status` time series for each service. The default is a curated
  set of common core Windows services. The singleton list `[all]` collects every installed
  service, one time series per service, typically a few hundred on a server, and more where
  per-user services add session-suffixed instances (Remote Desktop and Desktop Experience
  hosts). The `all` marker can't be combined with service names. Matching is exact and
  case-sensitive against the name the Service Control Manager reports. A name that isn't
  installed, or differs in case, produces no time series and no error.

* **`services.exclude`**
  Type: `array of string`. Optional.
  Exact service names to drop from collection, applied after `include`. Combine it with
  `include: [all]` to trim the collect-everything set.

* **`performance_counters`**
  Type: `object`. Optional.
  Settings for reading Windows performance counters as metrics. Off by default: define the
  counters to read and the metrics they map to, then enable it.

* **`performance_counters.enabled`**
  Type: `boolean`. Optional. Default: `false`.
  Whether to enable this configuration block. If true, the Collector runs the integration or
  capability. If false, the Collector doesn't run it.

* **`performance_counters.perfcounters`**
  Type: `array of object`. Optional. Minimum items: `1`.
  The performance counter objects to read, each with its counters and, for multi-instance
  objects, the instances to read. Every counter reads through the Performance Data Helper (PDH)
  library, so names are the English names shown in Performance Monitor, for example, object
  `Processor`, counter `% Processor Time`, instance `_Total`. Prefer the `_Total` instance for a
  bounded host aggregate. `*` reads every instance and produces one time series per instance, so
  for objects such as Process or Thread it multiplies time series by the number of instances.
  `_Total` can be listed alongside named instances, but is dropped under `*` because the
  per-instance time series already sum to it. Every counter must set `metric` to the name of an
  entry under `metrics`, which chooses the metric's name, unit, and type. Data points read
  through a wildcard or a named instance carry an `instance` attribute; a lone `_Total` reads as
  the object's aggregate without one.

* **`performance_counters.perfcounters[].instances`**
  Type: `array of string`. Optional.
  For a multi-instance object, the instances to read: named instances, `_Total` for the
  aggregate, or `*` for one time series per instance. `*` excludes `_Total`. Omit for a
  single-instance object.

* **`performance_counters.perfcounters[].object`**
  Type: `string`. Required. Minimum length: `1`.
  Performance object to read, by its English name as shown in Performance Monitor, for example,
  `Processor` or `LogicalDisk`.

* **`performance_counters.perfcounters[].counters`**
  Type: `array of object`. Required. Minimum items: `1`.
  The counters to read from this object. Each entry names a counter and the metric it maps to.

* **`performance_counters.perfcounters[].counters[].attributes`**
  Type: `object`. Optional.
  Static attributes attached to every data point this counter emits, as `name: value` pairs. Use
  them to tell apart counters that map to the same metric.

* **`performance_counters.perfcounters[].counters[].name`**
  Type: `string`. Required. Minimum length: `1`.
  Counter name within the object, by its English name as shown in Performance Monitor, for
  example, `% Processor Time`.

* **`performance_counters.perfcounters[].counters[].recreate_query`**
  Type: `boolean`. Optional.
  Whether to rebuild the counter query on every read. If true, the Collector recreates the query
  at each collection, which picks up instances that appear after startup at the cost of
  reopening the counter. If false, the Collector reuses the query opened at startup.

* **`performance_counters.perfcounters[].counters[].metric`**
  Type: `string`. Required. Minimum length: `1`.
  Name of the metric that this counter's values are emitted as. Must name an entry under
  `performance_counters.metrics`, which defines the metric's description, unit, and type.

* **`performance_counters.metrics`**
  Type: `object`. Optional.
  The metrics that counters can map to, keyed by metric name, each with a description, a unit
  (default `1`), and either `gauge: {}` or `sum: {aggregation: cumulative\|delta, monotonic:
  bool}`. Required when the capability is enabled, because every counter's `metric` must name a
  key defined here. That link isn't checked when the Collector validates its configuration: a
  counter that names an undefined metric stops performance counter collection at startup with a
  logged error, and every object's target health reads `0`.


## Related topics

- [Install Core Agent on Windows](/ingest/pipeline/v2/fleets/agent/windows-install.md)
- [Monitor data model](/investigate/alerts/monitors/data-model.md)
- [Design service level objectives](/administer/design-slos.md)
- [Querying delta temporality metrics](/investigate/querying/metrics/delta-queries.md)
- [Consumption licensing concepts](/administer/limits-licensing/concepts/consumption-licensing.md)