Skip to main content
The Windows integration requires CXDOT Collector 1.3.0 or greater. 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:

​
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.
  • To use checkpoint storage, create the directory and restrict permissions to the service account before enabling the store.

​
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:
  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:
    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:
    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:
    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:
    Set enabled: false directly under windows to disable the whole integration.
  6. Optional: Keep the read position across restarts. Checkpoint storage resumes each channel where it stopped when the Collector restarts. A crash can replay or lose up to one read batch. Create the directory and restrict permissions before enabling the store:
    If the Collector runs as an account other than Local System, grant that account Modify permission:
    Add the following to the Collector configuration file:
    A bookmark is never deleted, so a channel or query that returns after an absence resumes from its old bookmark and can collect everything the channel retained since. A change to a channel’s query, or to which integrations run on the host, starts that channel from the end once, on the restart that applies the change. Reordering or adding channels does not. A configuration shared between Linux and Windows hosts needs a per-host directory value, because the path is used as written on both.

​
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:
    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:
    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: Unless checkpoint storage is enabled, the integration collects only records written after the Collector starts. Without a custom query, it collects only Critical, Error, and Warning records.
  • Events written while the Collector was stopped are missing: Enable checkpoint storage. Without checkpoint storage, Event Log channels start from the end on each restart, which means records written while the Collector was down are skipped.
  • Old events flood in after a channel or checkpoint storage is added back: Bookmarks are never deleted. Stop the Collector, delete the channel’s bookmark file from the checkpoint directory, and start the Collector. Each channel’s bookmark file name ends with channel-, the first 16 characters of the lowercased channel name with punctuation replaced by -, another -, and the first 16 hexadecimal characters of the SHA-256 hash of the lowercased channel name. For example, the Application channel’s file name ends with channel-application-1fe289205936c3fd.
  • A channel reports health 1, but no records appear after enabling checkpoint storage: The Collector could not open its store at start. Check the Collector log for failed to start receiver with the directory path, confirm the service account has write permission, and restart.
  • Checkpoint storage fails to start, or bookmarks land in an unexpected directory, on a Windows host that shares its configuration with Linux hosts: directory is used as written on both operating systems. A Linux path such as /var/lib/cxdot-collector fails startup with directory must exist when create_directory is false, and is created as C:\var\lib\cxdot-collector on the drive the Collector runs from when it is true. Give each operating system its own directory value.
  • 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.

​
Configuration reference

Configure one Windows integration instance with the following settings. 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. Default: []. 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. Default: []. 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.