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 2019 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 and export Event Log records to your tenant. The default configuration requires no windows block. When the Collector runs as a Windows service, set a machine-scoped CHRONOSPHERE_API_TOKEN environment variable to your API token. The service doesn’t inherit variables from an interactive session, regardless of how you register it. For example, from an elevated PowerShell session:
    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 omits the _Total instance. To keep _Total as its own time series with an instance attribute, list it with *, as in instances: ["*", "_Total"].
  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 doesn’t. 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. The query matches both EventLog and eventlog because some tenants store label values in lowercase.
  3. On the Windows host, from an elevated command prompt, write a test Warning to the Application log:
    In Logs Explorer, filter for ["cxdot.integration.name"] = "windows" AND "Windows integration test". Confirm that the record 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

  • The Collector Windows service doesn’t start, and the System log shows only service error 7023 or error 1064: When the Service Control Manager runs the Collector, the Collector writes its logs, including the startup error, to the Application log. The event source is the registered service name, such as cxdot-collector. Nothing registers that event source, so Event Viewer might wrap each entry in a message that says the description for the event ID from that source can’t be found. The message text from the Collector follows that wrapper. To write the logs to a file instead, set service.telemetry.logs.output_paths in the Collector configuration file. For example:
    Setting a file replaces the Event Log output for the service. Setting stdout or stderr doesn’t.
  • The Collector service doesn’t start after a host reboot or crash, and the log shows bind: Only one usage of each socket address (protocol/network address/port) is normally permitted for a debug.sock path: An unclean exit left the debug socket file of the cxdotdebug extension behind. Collector versions 1.1.0 through 1.14.0 don’t remove the file and fail every later start. Versions after 1.14.0 remove a leftover socket file that nothing is serving at startup. On an affected version, delete the file at the cxdot.debug.socket_path path and start the service. The default path is /var/run/cxdot-collector/debug.sock, which on Windows resolves on the system drive, such as C:\var\run\cxdot-collector\debug.sock. Upgrade the Collector to resolve the problem permanently.
  • The Collector service doesn’t retry after it fails to start: By default, the Service Control Manager applies a service’s recovery actions only when the service crashes, not when it fails to start. From an elevated command prompt, set the restart actions and enable them for failures that aren’t crashes:
    Replace cxdot-collector with the registered service name if it differs. The service restarts after 5 seconds, then 5 seconds, then 60 seconds, and the failure count resets after a day without failures. The failureflag setting makes the recovery actions apply to a start that exits with an error.
  • 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. Also confirm that a logs exporter is configured. If you use tenant egress, enable cxdot.egress.tenant.signals.logs.enabled: true.
  • No records from the Collector service appear in exported Event Log records: The integration always excludes the Collector service’s own event provider from every channel, so the Collector doesn’t ingest its own error logs. The provider name matches the registered Windows service name. The default exclusion is cxdot-collector, which applies when the service is registered under that name.
  • 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 filename 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 Secure Hash Algorithm (SHA)-256 hash of the lowercased channel name. For example, the Application channel’s filename ends with channel-application-1fe289205936c3fd.
  • A channel reports health 1, but no records appear after enabling checkpoint storage: The Collector couldn’t 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’s 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 alone omits _Total. List both in the object’s instances, as in instances: ["*", "_Total"], to keep _Total with its instance attribute.

Move the debug socket

Requires CXDOT Collector v1.16.0 or later.
The Collector serves its debug views, which the cxdot-admin tool reads, on a socket file at the cxdot.debug.socket_path path. The default path, /var/run/cxdot-collector/debug.sock, resolves on the system drive, such as C:\var\run\cxdot-collector\debug.sock. Anyone who can reach the socket can read every debug view. To put the socket in a directory that only the Collector and administrators can access, follow these steps:
  1. From an elevated command prompt, create the directory and restrict its permissions:
    Skip this step if you already created the directory to enable checkpoint storage. If the Collector runs as an account other than Local System, grant that account Modify permission on the directory.
  2. Add the following to the Collector configuration file:
    A drive-letter path requires schema_version: v1.16 or later. At an earlier schema_version, the path must start with /, such as /ProgramData/cxdot-collector/debug.sock, which resolves on the system drive.
  3. Restart the Collector.
  4. From an elevated command prompt, pass the same path to cxdot-admin with --socket, or set the CXDOT_DEBUG_SOCKET environment variable to it. The permissions from step 1 require elevation. For example:
    Without either, cxdot-admin reads the default path.

Enable checkpoint storage

Requires CXDOT Collector v1.6.0+otel-0.158.0 or later.
The CXDOT Collector can use checkpoint storage for Windows Event Log channels collected by the Windows integration. If checkpoint storage is enabled, the Collector saves its log read positions for each channel to disk, and will resume from those saved positions if the Collector restarts. This lets the Collector retrieve logs written by Windows Event Log while the Collector was stopped. If checkpoint storage is disabled, the Collector starts reading logs from the end of each channel after a restart, and won’t collect any logs written while it was stopped. Checkpoint storage is disabled by default. To enable it, follow these steps:
  1. Create a directory where the Collector can save checkpoint files. The Collector must have write permissions for this directory, and Palo Alto Networks recommends restricting access to this directory so that other users or processes can’t write to it.
  2. Add the following values to your CXDOT Collector configuration file:
    Replace PATH with the absolute path to the directory that you created in the previous step.
  3. Optional: Add fsync: true to your CXDOT Collector configuration file:
    This setting is disabled by default. If fsync is enabled, the Collector saves its log read positions to disk immediately, which reduces the chance of losing the latest checkpoint during an restart, but increases the number of writes to disk. If fsync is disabled, the operation system controls when to write checkpoints to disk.
  4. Restart the CXDOT Collector.
  5. Confirm that the directory you created contains a checkpoint file. Checkpoint filenames begin with receiver_.

Delete checkpoint files

The CXDOT Collector doesn’t delete checkpoint files. Outdated checkpoint files can create unnecessary backlogs in certain scenarios, so Palo Alto Networks recommends deleting any files in the checkpoint directory if you’re re-enabling checkpoint storage after an extended period of time. Additionally, if you remove a Windows Event Log channel, Palo Alto Networks recommends deleting its associated checkpoint file before restoring that channel. To delete checkpoint files, follow these steps:
  1. Stop the Collector. Never delete checkpoint files while the Collector is running.
  2. Delete the files in the Collector’s checkpoint directory. If you plan to continue using checkpoint storage, don’t delete the directory itself. To delete the checkpoint file for a specific Windows Event Log channel, determine which file is associated with that channel. The name of each checkpoint file ends with a hexadecimal string derived from the name of its associated channel. For example, a channel named Application will have a checkpoint file whose filename ends in e7ad522ea327e5ba. Use the following PowerShell command to calculate the hexadecimal string for a specified channel name:
    Replace CHANNEL with the name of your channel.
  3. Start the Collector.

Troubleshoot checkpoint storage

Use the following information to troubleshoot issues with checkpoint storage.
  • The Collector doesn’t start, and returns the message directory must exist: The path in directory doesn’t exist, or isn’t a directory. Correct the path or create the directory. On Linux, setting create_directory to true also resolves this issue.
  • The Collector starts and reports healthy, but log records stop arriving after you enable checkpoint storage: The Collector can’t write to the directory. The Collector validates only that the directory exists, so it starts normally, but each log receiver fails when it opens its checkpoint file. Check the Collector log for an error that includes the checkpoint directory path. Grant the Collector write permission on the directory and then restart the Collector.
  • Records written while the Collector was stopped are missing: Confirm that enabled is true, that the Collector runs with mode: host on Linux or Windows, and that the Collector version supports checkpoint storage on that operating system. The first start after you enable checkpoint storage doesn’t collect earlier records.
  • Old records arrive after you enable checkpoint storage again or add a Windows channel back: The Collector resumed from a stale read position. Stop the Collector, delete the affected bookmark files from the checkpoint directory, and start the Collector.

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. * alone omits _Total, because the per-instance time series already sum to it. To keep _Total alongside every other instance, list both, as in instances: ["*", "_Total"]. 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, including _Total when you list it with *; a lone _Total reads as the object’s aggregate without one.
  • performance_counters.perfcounters[].aggregation_name Type: string. Optional. Name of the instance that aggregates all other instances of this object, for objects whose aggregate isn’t called _Total, such as _Global_. The Collector omits this instance when it’s read with other instances, and clears its instance attribute when it’s read alone. To keep it alongside *, set this field and list the same name in instances, for example, instances: ["*", "_Global_"].
  • 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[].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.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[].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. * alone omits _Total. To keep _Total as its own time series with an instance attribute, list it with *: ["*", "_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.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.