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:-
Run the Collector in host mode and export Event Log records to your tenant. The
default configuration requires no
windowsblock. When the Collector runs as a Windows service, set a machine-scopedCHRONOSPHERE_API_TOKENenvironment 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: -
Optional: Select the Event Log channels to collect. The
channelslist 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’squeryto 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. -
Optional: Select the services to monitor. Use exact Service Control Manager
service names, including capitalization. Run
Get-Servicein PowerShell to find the service names on the host. For example, add the following to the Collector configuration file:Setincludeto[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. -
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
_Totalfor a bounded aggregate when an object has multiple instances. The*instance selector creates one time series for every matching instance and omits the_Totalinstance. To keep_Totalas its own time series with aninstanceattribute, list it with*, as ininstances: ["*", "_Total"]. -
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: falsedirectly underwindowsto disable the whole integration. -
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
directoryvalue, because the path is used as written on both.
Validate
To validate the Windows integration, follow these steps:-
In Live Telemetry Analyzer, filter for
__name__=cxdot.integration.target.health cxdot.integration.name=windows. Confirm that each configured target reports1. Use thecxdot.integration.checkandcxdot.integration.targetattributes to identify the capability and target for each result. -
In Metrics Explorer, run the following query:
Confirm that the query returns a time series for the Windows Event Log service. A value of
4means the service is running. The query matches bothEventLogandeventlogbecause some tenants store label values in lowercase. -
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. -
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, setservice.telemetry.logs.output_pathsin the Collector configuration file. For example:Setting a file replaces the Event Log output for the service. Settingstdoutorstderrdoesn’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 permittedfor adebug.sockpath: An unclean exit left the debug socket file of thecxdotdebugextension 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 thecxdot.debug.socket_pathpath and start the service. The default path is/var/run/cxdot-collector/debug.sock, which on Windows resolves on the system drive, such asC:\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-collectorwith 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. Thefailureflagsetting 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, enablecxdot.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, theApplicationchannel’s filename ends withchannel-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 forfailed to start receiverwith 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:
directoryis used as written on both operating systems. A Linux path such as/var/lib/cxdot-collectorfails startup withdirectory must existwhencreate_directoryis false, and is created asC:\var\lib\cxdot-collectoron the drive the Collector runs from when it’s true. Give each operating system its owndirectoryvalue. -
A configured service has no status time series: Confirm that
services.includecontains 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.statusmetric 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’smetricvalue matches a key undermetrics. 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
_Totaltime series is missing from wildcard collection: The*selector alone omits_Total. List both in the object’sinstances, as ininstances: ["*", "_Total"], to keep_Totalwith itsinstanceattribute.
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:
-
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.
-
Add the following to the Collector configuration file:
A drive-letter path requires
schema_version: v1.16or later. At an earlierschema_version, the path must start with/, such as/ProgramData/cxdot-collector/debug.sock, which resolves on the system drive. - Restart the Collector.
-
From an elevated command prompt, pass the same path to
cxdot-adminwith--socket, or set theCXDOT_DEBUG_SOCKETenvironment variable to it. The permissions from step 1 require elevation. For example:Without either,cxdot-adminreads 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:
- 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.
-
Add the following values to your CXDOT Collector configuration file:
Replace
PATHwith the absolute path to the directory that you created in the previous step. -
Optional: Add
fsync: trueto your CXDOT Collector configuration file:This setting is disabled by default. Iffsyncis 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. Iffsyncis disabled, the operation system controls when to write checkpoints to disk. - Restart the CXDOT Collector.
-
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:- Stop the Collector. Never delete checkpoint files while the Collector is running.
-
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
Applicationwill have a checkpoint file whose filename ends ine7ad522ea327e5ba. Use the following PowerShell command to calculate the hexadecimal string for a specified channel name:ReplaceCHANNELwith the name of your channel. - 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 indirectorydoesn’t exist, or isn’t a directory. Correct the path or create the directory. On Linux, settingcreate_directorytotruealso 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
enabledistrue, that the Collector runs withmode: hoston 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 undercxdot.integrations.windows.
Optional settings
-
enabledType: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_intervalType: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 onevent_logs.poll_intervalinstead. -
timeoutType: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_logsType:object. Optional. Settings for collecting Windows Event Log records as log telemetry. -
event_logs.enabledType: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.channelsType: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[].channelType: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[].queryType: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_providersType:array of string. Optional. Default:[]. Event providers to drop after reading, for a provider that’s noisy or can’t render. Prefer narrowingquery, 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_intervalType: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_readsType: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. -
servicesType:object. Optional. Settings for collecting Windows service states, onewindows.service.statustime series per service. -
services.enabledType: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.includeType: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, onewindows.service.statustime 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). Theallmarker 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.excludeType:array of string. Optional. Default:[]. Exact service names to drop from collection, applied afterinclude. Combine it withinclude: [all]to trim the collect-everything set. -
performance_countersType: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.enabledType: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.perfcountersType: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, objectProcessor, counter% Processor Time, instance_Total. Prefer the_Totalinstance 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_Totalalongside every other instance, list both, as ininstances: ["*", "_Total"]. Every counter must setmetricto the name of an entry undermetrics, which chooses the metric’s name, unit, and type. Data points read through a wildcard or a named instance carry aninstanceattribute, including_Totalwhen you list it with*; a lone_Totalreads as the object’s aggregate without one. -
performance_counters.perfcounters[].aggregation_nameType: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 itsinstanceattribute when it’s read alone. To keep it alongside*, set this field and list the same name ininstances, for example,instances: ["*", "_Global_"]. -
performance_counters.perfcounters[].countersType: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[].attributesType:object. Optional. Static attributes attached to every data point this counter emits, asname: valuepairs. Use them to tell apart counters that map to the same metric. -
performance_counters.perfcounters[].counters[].metricType:string. Required. Minimum length:1. Name of the metric that this counter’s values are emitted as. Must name an entry underperformance_counters.metrics, which defines the metric’s description, unit, and type. -
performance_counters.perfcounters[].counters[].nameType: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_queryType: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[].instancesType:array of string. Optional. For a multi-instance object, the instances to read: named instances,_Totalfor the aggregate, or*for one time series per instance.*alone omits_Total. To keep_Totalas its own time series with aninstanceattribute, list it with*:["*", "_Total"]. Omit for a single-instance object. -
performance_counters.perfcounters[].objectType:string. Required. Minimum length:1. Performance object to read, by its English name as shown in Performance Monitor, for example,ProcessororLogicalDisk. -
performance_counters.metricsType:object. Optional. The metrics that counters can map to, keyed by metric name, each with a description, a unit (default1), and eithergauge: {}orsum: {aggregation: cumulative\|delta, monotonic: bool}. Required when the capability is enabled, because every counter’smetricmust 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 reads0.