Add per_user services filter to windows_service (#24088) (#24204)

* Add per_user services filter criterion to windows_service

Add a per_user (true/false) match criterion to the services filter,
mirroring trigger_start, to select services by whether they are Windows
per-user service instances. Configure per_user: false to exclude per-user
services from collection. Warn when grouping is enabled alongside a
per_user: false filter, since excluded services cannot be grouped.

* Add changelog entry

* Reuse ServiceAssertion in per_user tests

Use the existing ServiceAssertion / assert_service_check_and_metrics
helpers in the per_user tests for consistency with the rest of the suite;
this also asserts the uptime/state/restarts metrics, not just the service
check.

* Read service_type from ServiceView instead of a match() parameter

Pass the enumeration's ServiceType into ServiceView and have ServiceFilter.match
read service_view.service_type, consistent with how it reads the other service
properties, rather than threading service_type through match() as an argument.

* Make ServiceView.service_type lazy with config fallback

Read service_type from the service config when it was not provided to the
constructor, caching like the other ServiceView properties, and include it
in __str__.

(cherry picked from commit 3ca0f7d)

Co-authored-by: Branden Clark <branden.clark@datadoghq.com>

Author: dd-octo-sts[bot]

windows_service/assets/configuration/spec.yaml

@@ -24,6 +24,14 @@ files:
                 - true
                 - false
 
+              Services can also be selectively monitored by whether they are Windows per-user services,
+              which are instantiated per user logon session and named `<service name>_<LUID>`
+              (for example `OneSyncSvc_443f50`). The possible values for `per_user` are:
+                - true
+                - false
+              To exclude per-user services from collection, monitor only non-per-user services with
+              `per_user: false`.
+
               If any service is set to `ALL`, all services registered with the SCM will be monitored, and
               all other patterns provided in this instance will be ignored.
 
@@ -45,6 +53,7 @@ files:
                 - name: <SERVICE_NAME_2>
                 - startup_type: automatic
                   trigger_start: false
+                - per_user: false
           - name: disable_legacy_service_tag
             description: |
               Whether or not to stop submitting the tag `service` that has been renamed

windows_service/changelog.d/24088.added

@@ -0,0 +1 @@
+Add a `per_user` services filter criterion to select or exclude Windows per-user services (use `per_user: false` to exclude them from collection).

windows_service/datadog_checks/windows_service/data/conf.yaml.example

@@ -27,6 +27,14 @@ instances:
     ##   - true
     ##   - false
     ##
+    ## Services can also be selectively monitored by whether they are Windows per-user services,
+    ## which are instantiated per user logon session and named `<service name>_<LUID>`
+    ## (for example `OneSyncSvc_443f50`). The possible values for `per_user` are:
+    ##   - true
+    ##   - false
+    ## To exclude per-user services from collection, monitor only non-per-user services with
+    ## `per_user: false`.
+    ##
     ## If any service is set to `ALL`, all services registered with the SCM will be monitored, and
     ## all other patterns provided in this instance will be ignored.
     ##
@@ -41,6 +49,7 @@ instances:
       - name: <SERVICE_NAME_2>
       - startup_type: automatic
         trigger_start: false
+      - per_user: false
 
     ## @param disable_legacy_service_tag - boolean - optional - default: false
     ## Whether or not to stop submitting the tag `service` that has been renamed

windows_service/datadog_checks/windows_service/windows_service.py

@@ -22,9 +22,14 @@
 USER_SERVICE_LUID_SUFFIX_RE = re.compile(r'_[0-9A-Fa-f]+$')
 
 
+def _is_per_user_service(service_type: int) -> bool:
+    """True for per-user service instances (named <template>_<LUID>)."""
+    return bool(service_type & SERVICE_USERSERVICE_INSTANCE)
+
+
 def _group_per_user_service_name(name: str, service_type: int) -> str:
     """Strip the per-user LUID suffix so instances group under their template name."""
-    if service_type & SERVICE_USERSERVICE_INSTANCE:
+    if _is_per_user_service(service_type):
         return USER_SERVICE_LUID_SUFFIX_RE.sub('', name)
     return name
 
@@ -42,10 +47,11 @@ class TriggerInfo(ctypes.Structure):
 
 
 class ServiceFilter(object):
-    def __init__(self, name=None, startup_type=None, trigger_start=None):
+    def __init__(self, name=None, startup_type=None, trigger_start=None, per_user=None):
         self.name = name
         self.startup_type = startup_type
         self.trigger_start = trigger_start
+        self.per_user = per_user
 
         self._init_patterns()
 
@@ -61,6 +67,9 @@ def match(self, service_view):
         if self.name is not None:
             if not self._name_re.match(service_view.name):
                 return False
+        if self.per_user is not None:
+            if self.per_user != _is_per_user_service(service_view.service_type):
+                return False
         if self.startup_type is not None:
             if self.startup_type.lower() != service_view.startup_type_string().lower():
                 return False
@@ -79,6 +88,8 @@ def __str__(self):
             vals.append('startup_type={}'.format(self.startup_type))
         if self.trigger_start is not None:
             vals.append('trigger_start={}'.format(self.trigger_start))
+        if self.per_user is not None:
+            vals.append('per_user={}'.format(self.per_user))
         # Example:
         #   - ServiceFilter(name=EventLog)
         #   - ServiceFilter(startup_type=automatic)
@@ -113,7 +124,8 @@ def from_config(cls, item, wmi_compat=False):
                 name = cls._wmi_compat_name(name)
             startup_type = item.get('startup_type', None)
             trigger_start = item.get('trigger_start', None)
-            obj = cls(name=name, startup_type=startup_type, trigger_start=trigger_start)
+            per_user = item.get('per_user', None)
+            obj = cls(name=name, startup_type=startup_type, trigger_start=trigger_start, per_user=per_user)
         else:
             raise Exception("Invalid type '{}' for service".format(type(item).__name__))
         return obj
@@ -130,7 +142,7 @@ class ServiceView(object):
     STARTUP_TYPE_UNKNOWN = "unknown"
     DISPLAY_NAME_UNKNOWN = "Not_Found"
 
-    def __init__(self, scm_handle, name):
+    def __init__(self, scm_handle, name, service_type=None):
         self.scm_handle = scm_handle
         self.name = name
 
@@ -139,11 +151,14 @@ def __init__(self, scm_handle, name):
         self._service_config = None
         self._is_delayed_auto = None
         self._trigger_count = None
+        self._service_type = service_type
 
     def __str__(self):
         vals = []
         if self.name is not None:
             vals.append('name={}'.format(self.name))
+        if self._service_type is not None:
+            vals.append('service_type=0x{:X}'.format(self._service_type))
         if self._startup_type is not None:
             vals.append('startup_type={}'.format(self.startup_type_string()))
         if self._trigger_count is not None:
@@ -167,6 +182,12 @@ def service_config(self):
             self._service_config = win32service.QueryServiceConfig(self.hSvc)
         return self._service_config
 
+    @property
+    def service_type(self):
+        if self._service_type is None:
+            self._service_type = self.service_config[0]
+        return self._service_type
+
     @property
     def startup_type(self):
         if self._startup_type is None:
@@ -317,14 +338,22 @@ def check(self, instance):
 
         group_per_user_services = instance.get('group_per_user_services', False)
 
+        # Exclusion (per_user: false) takes precedence over grouping; excluded services are never
+        # collected, so they can't be grouped.
+        if group_per_user_services and any(f.per_user is False for f in service_filters):
+            self.warning(
+                "group_per_user_services is enabled but a services filter excludes per-user services "
+                "(per_user: false); excluded services are not collected and will not be grouped."
+            )
+
         for service_status_process_enum in service_status_process_enums:
             service_name = service_status_process_enum["ServiceName"]
             display_name = service_status_process_enum["DisplayName"]
             state = service_status_process_enum["CurrentState"]
             service_pid = service_status_process_enum["ProcessId"]
             service_type = service_status_process_enum.get("ServiceType", 0)
 
-            service_view = ServiceView(scm_handle, service_name)
+            service_view = ServiceView(scm_handle, service_name, service_type)
 
             # Names used for tags; for per-user services these collapse the per-session LUID suffix
             # so all instances report under their template name.

windows_service/tests/test_windows_service.py

@@ -505,6 +505,68 @@ def test_group_per_user_services_with_name_filter(aggregator, check, instance_gr
     assert_service_check_and_metrics(aggregator, services)
 
 
+def test_per_user_false_excludes_per_user_services(aggregator, check):
+    # `per_user: false` collects only non-per-user services, so per-user instances are dropped.
+    instance = {'services': [{'per_user': False}], 'disable_legacy_service_tag': True}
+    c = check(instance)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=_per_user_mock_services()):
+        c.check(instance)
+
+    services = [
+        ServiceAssertion('Dnscache', win32service.SERVICE_RUNNING),
+        ServiceAssertion('OneSyncSvc_443f50', win32service.SERVICE_RUNNING, count=0),
+        ServiceAssertion('OneSyncSvc_18f113', win32service.SERVICE_RUNNING, count=0),
+    ]
+    assert_service_check_and_metrics(aggregator, services)
+
+
+def test_per_user_true_collects_only_per_user_services(aggregator, check):
+    instance = {'services': [{'per_user': True}], 'disable_legacy_service_tag': True}
+    c = check(instance)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=_per_user_mock_services()):
+        c.check(instance)
+
+    services = [
+        ServiceAssertion('OneSyncSvc_443f50', win32service.SERVICE_RUNNING),
+        ServiceAssertion('OneSyncSvc_18f113', win32service.SERVICE_RUNNING),
+        ServiceAssertion('Dnscache', win32service.SERVICE_RUNNING, count=0),
+    ]
+    assert_service_check_and_metrics(aggregator, services)
+
+
+def test_per_user_composes_with_name_filter(aggregator, check):
+    # A name filter that matches the per-user instances but is gated to non-per-user collects nothing.
+    instance = {'services': [{'name': 'OneSyncSvc', 'per_user': False}], 'disable_legacy_service_tag': True}
+    c = check(instance)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=_per_user_mock_services()):
+        c.check(instance)
+
+    services = [
+        ServiceAssertion('OneSyncSvc_443f50', win32service.SERVICE_RUNNING, count=0),
+        ServiceAssertion('OneSyncSvc_18f113', win32service.SERVICE_RUNNING, count=0),
+        # The named filter still goes unmatched and reports UNKNOWN once.
+        ServiceAssertion('OneSyncSvc', -1, count=1),
+    ]
+    assert_service_check_and_metrics(aggregator, services)
+
+
+def test_per_user_false_with_grouping_warns(aggregator, check):
+    instance = {
+        'services': [{'per_user': False}],
+        'group_per_user_services': True,
+        'disable_legacy_service_tag': True,
+    }
+    c = check(instance)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=_per_user_mock_services()):
+        c.check(instance)
+
+    assert any('will not be grouped' in w for w in c.warnings)
+
+
 @pytest.mark.e2e
 def test_basic_e2e(dd_agent_check, check, instance_basic):
     aggregator = dd_agent_check(instance_basic)