Add group_per_user_services option to windows_service (#24087)

* Add group_per_user_services option to windows_service

Strip the per-session LUID suffix from Windows per-user service instances
so they report under their template name, reducing windows_service and
display_name tag cardinality. Detection gates on the
SERVICE_USERSERVICE_INSTANCE type flag plus a trailing _<LUID> suffix.
Defaults to false.

* Address review: type hints, comment, filter-mode test

Add type hints to _group_per_user_service_name and drop the redundant
suffix-search guard. Document the grouped-instance behavior (instances
collapse to one series; last-emitted state wins) as a code comment.
Add a test covering grouping when services are selected by name filter.

* Add changelog entry

* Reuse ServiceAssertion in group_per_user tests

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

Author: clarkb7

windows_service/assets/configuration/spec.yaml

@@ -82,4 +82,18 @@ files:
             value:
               type: boolean
               example: false
+          - name: group_per_user_services
+            description: |
+              Whether or not to group Windows per-user services under their template name.
+
+              Per-user services are instantiated per user logon session and named
+              `<service name>_<LUID>` (for example `OneSyncSvc_443f50`), which creates high
+              cardinality in the `windows_service` and `display_name` tags. When enabled, the
+              LUID suffix is stripped so all instances of a per-user service report under the
+              same template name.
+              See https://learn.microsoft.com/en-us/windows/application-management/per-user-services-in-windows
+            fleet_configurable: true
+            value:
+              type: boolean
+              example: false
           - template: instances/default

windows_service/changelog.d/24087.added

@@ -0,0 +1 @@
+Add the `group_per_user_services` option to report Windows per-user service instances under their template name, reducing `windows_service` tag cardinality.

windows_service/datadog_checks/windows_service/config_models/defaults.py

@@ -28,6 +28,10 @@ def instance_enable_legacy_tags_normalization():
     return True
 
 
+def instance_group_per_user_services():
+    return False
+
+
 def instance_min_collection_interval():
     return 15
 

windows_service/datadog_checks/windows_service/config_models/instance.py

@@ -40,6 +40,7 @@ class InstanceConfig(BaseModel):
     disable_legacy_service_tag: Optional[bool] = None
     empty_default_hostname: Optional[bool] = None
     enable_legacy_tags_normalization: Optional[bool] = None
+    group_per_user_services: Optional[bool] = None
     metric_patterns: Optional[MetricPatterns] = None
     min_collection_interval: Optional[float] = None
     service: Optional[str] = None

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

@@ -73,6 +73,18 @@ instances:
     #
     # collect_display_name_as_tag: false
 
+    ## @param group_per_user_services - boolean - optional - default: false
+    ## Whether or not to group Windows per-user services under their template name.
+    ##
+    ## Per-user services are instantiated per user logon session and named
+    ## `<service name>_<LUID>` (for example `OneSyncSvc_443f50`), which creates high
+    ## cardinality in the `windows_service` and `display_name` tags. When enabled, the
+    ## LUID suffix is stripped so all instances of a per-user service report under the
+    ## same template name.
+    ## See https://learn.microsoft.com/en-us/windows/application-management/per-user-services-in-windows
+    #
+    # group_per_user_services: false
+
     ## @param tags - list of strings - optional
     ## A list of tags to attach to every metric and service check emitted by this instance.
     ##

windows_service/datadog_checks/windows_service/windows_service.py

@@ -16,6 +16,18 @@
 
 SERVICE_CONFIG_TRIGGER_INFO = 8
 
+# Per-user service instance flag (SERVICE_USERSERVICE_INSTANCE in winsvc.h). Set on the
+# per-session instances of a per-user service (named <template>_<LUID>), not on the template.
+SERVICE_USERSERVICE_INSTANCE = 0x80
+USER_SERVICE_LUID_SUFFIX_RE = re.compile(r'_[0-9A-Fa-f]+$')
+
+
+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:
+        return USER_SERVICE_LUID_SUFFIX_RE.sub('', name)
+    return name
+
 
 def QueryServiceConfig2W(*args):
     """
@@ -303,14 +315,31 @@ def check(self, instance):
         # See test_name_regex_order()
         service_filters = sorted(service_filters, reverse=True, key=lambda x: len(x.name or ""))
 
+        group_per_user_services = instance.get('group_per_user_services', False)
+
         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)
 
+            # Names used for tags; for per-user services these collapse the per-session LUID suffix
+            # so all instances report under their template name.
+            # The full instance name is kept for service handles and the restart PID cache.
+            # Multiple instances thus collapse into a single series; if they are in different states
+            # the reported state reflects whichever instance is emitted last.
+            # We generally expect multiple per-user instances per host to be rare (terminal service
+            # sessions only); the main win is grouping the windows_service tag across hosts (and thus
+            # service checks) for easier monitoring.
+            reported_name = service_name
+            reported_display_name = display_name
+            if group_per_user_services:
+                reported_name = _group_per_user_service_name(service_name, service_type)
+                reported_display_name = _group_per_user_service_name(display_name, service_type)
+
             if 'ALL' not in services:
                 for service_filter in service_filters:
                     try:
@@ -338,11 +367,11 @@ def check(self, instance):
             status = self.STATE_TO_STATUS.get(state, self.UNKNOWN)
             state_string = self.STATE_TO_STRING.get(state, self.UNKNOWN_LITERAL)
 
-            tags = ['windows_service:{}'.format(service_name), 'windows_service_state:{}'.format(state_string)]
+            tags = ['windows_service:{}'.format(reported_name), 'windows_service_state:{}'.format(state_string)]
             tags.extend(custom_tags)
 
             if instance.get('collect_display_name_as_tag', False):
-                tags.append('display_name:{}'.format(display_name))
+                tags.append('display_name:{}'.format(reported_display_name))
 
             if instance.get('windows_service_startup_type_tag', False):
                 try:
@@ -355,7 +384,7 @@ def check(self, instance):
 
             if not instance.get('disable_legacy_service_tag', False):
                 self._log_deprecation('service_tag', 'windows_service')
-                tags.append('service:{}'.format(service_name))
+                tags.append('service:{}'.format(reported_name))
 
             self.service_check(self.SERVICE_CHECK_NAME, status, tags=tags)
             self.log.debug('service state for %s %s', service_name, status)

windows_service/tests/common.py

@@ -44,6 +44,12 @@
     ],
     'disable_legacy_service_tag': True,
 }
+INSTANCE_GROUP_PER_USER_SERVICES = {
+    'services': ['ALL'],
+    'group_per_user_services': True,
+    'collect_display_name_as_tag': True,
+    'disable_legacy_service_tag': True,
+}
 INSTANCE_TRIGGER_START = {
     'services': [
         {'name': 'eventlog', 'startup_type': 'automatic', 'trigger_start': False},

windows_service/tests/conftest.py

@@ -65,6 +65,11 @@ def instance_trigger_start():
     return deepcopy(common.INSTANCE_TRIGGER_START)
 
 
+@pytest.fixture
+def instance_group_per_user_services():
+    return deepcopy(common.INSTANCE_GROUP_PER_USER_SERVICES)
+
+
 @pytest.fixture
 def instance_name_regex_prefix():
     return deepcopy(common.INSTANCE_PREFIX_MATCH)

windows_service/tests/test_windows_service.py

@@ -389,6 +389,122 @@ def test_service_restart_detection(aggregator, check, instance_basic):
     )
 
 
+# Per-user service instances carry SERVICE_USER_OWN_PROCESS (0x50) plus the
+# SERVICE_USERSERVICE_INSTANCE flag (0x80). Templates (not enumerated) lack the 0x80 bit.
+USER_SERVICE_INSTANCE_TYPE = 0x10 | 0x40 | 0x80
+WIN32_OWN_PROCESS_TYPE = 0x10
+
+
+def _per_user_mock_services():
+    return [
+        {
+            'ServiceName': 'OneSyncSvc_443f50',
+            'DisplayName': 'Sync Host_443f50',
+            'CurrentState': win32service.SERVICE_RUNNING,
+            'ProcessId': 1234,
+            'ServiceType': USER_SERVICE_INSTANCE_TYPE,
+        },
+        {
+            'ServiceName': 'OneSyncSvc_18f113',
+            'DisplayName': 'Sync Host_18f113',
+            'CurrentState': win32service.SERVICE_RUNNING,
+            'ProcessId': 5678,
+            'ServiceType': USER_SERVICE_INSTANCE_TYPE,
+        },
+        {
+            'ServiceName': 'Dnscache',
+            'DisplayName': 'DNS Client',
+            'CurrentState': win32service.SERVICE_RUNNING,
+            'ProcessId': 9999,
+            'ServiceType': WIN32_OWN_PROCESS_TYPE,
+        },
+    ]
+
+
+def test_group_per_user_services(aggregator, check, instance_group_per_user_services):
+    c = check(instance_group_per_user_services)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=_per_user_mock_services()):
+        c.check(instance_group_per_user_services)
+
+    services = [
+        # Both per-user instances collapse to the template name, so the grouped tag is submitted twice
+        ServiceAssertion('OneSyncSvc', win32service.SERVICE_RUNNING, extra_tags=['display_name:Sync Host'], count=2),
+        # The LUID-suffixed names must no longer be emitted
+        ServiceAssertion('OneSyncSvc_443f50', win32service.SERVICE_RUNNING, count=0),
+        ServiceAssertion('OneSyncSvc_18f113', win32service.SERVICE_RUNNING, count=0),
+        # Non per-user services are untouched
+        ServiceAssertion('Dnscache', win32service.SERVICE_RUNNING, extra_tags=['display_name:DNS Client']),
+    ]
+    assert_service_check_and_metrics(aggregator, services)
+
+
+def test_group_per_user_services_disabled(aggregator, check, instance_group_per_user_services):
+    instance_group_per_user_services['group_per_user_services'] = False
+    c = check(instance_group_per_user_services)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=_per_user_mock_services()):
+        c.check(instance_group_per_user_services)
+
+    services = [
+        # Without grouping each instance keeps its full LUID-suffixed name
+        ServiceAssertion(
+            'OneSyncSvc_443f50', win32service.SERVICE_RUNNING, extra_tags=['display_name:Sync Host_443f50']
+        ),
+        ServiceAssertion(
+            'OneSyncSvc_18f113', win32service.SERVICE_RUNNING, extra_tags=['display_name:Sync Host_18f113']
+        ),
+        # The grouped template name is not emitted
+        ServiceAssertion('OneSyncSvc', win32service.SERVICE_RUNNING, count=0),
+    ]
+    assert_service_check_and_metrics(aggregator, services)
+
+
+def test_group_per_user_services_ignores_non_user_service(aggregator, check, instance_group_per_user_services):
+    # A regular service whose name happens to end in _<hex> must not be stripped: it lacks the
+    # SERVICE_USERSERVICE_INSTANCE flag.
+    mock_services = [
+        {
+            'ServiceName': 'MyService_abc123',
+            'DisplayName': 'My Service_abc123',
+            'CurrentState': win32service.SERVICE_RUNNING,
+            'ProcessId': 4242,
+            'ServiceType': WIN32_OWN_PROCESS_TYPE,
+        },
+    ]
+    c = check(instance_group_per_user_services)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=mock_services):
+        c.check(instance_group_per_user_services)
+
+    services = [
+        ServiceAssertion(
+            'MyService_abc123', win32service.SERVICE_RUNNING, extra_tags=['display_name:My Service_abc123']
+        ),
+    ]
+    assert_service_check_and_metrics(aggregator, services)
+
+
+def test_group_per_user_services_with_name_filter(aggregator, check, instance_group_per_user_services):
+    # Grouping must also apply when services are selected by a name filter (not just ALL). The
+    # prefix regex matches the full LUID-suffixed instance names, but the emitted tag is grouped.
+    instance_group_per_user_services['services'] = ['OneSyncSvc']
+
+    c = check(instance_group_per_user_services)
+
+    with patch('win32service.EnumServicesStatusEx', return_value=_per_user_mock_services()):
+        c.check(instance_group_per_user_services)
+
+    services = [
+        ServiceAssertion('OneSyncSvc', win32service.SERVICE_RUNNING, extra_tags=['display_name:Sync Host'], count=2),
+        # The grouped template name must not be reported UNKNOWN by the services_unseen path
+        ServiceAssertion('OneSyncSvc', -1, count=0),
+        # The non-matching service is not reported
+        ServiceAssertion('Dnscache', win32service.SERVICE_RUNNING, count=0),
+    ]
+    assert_service_check_and_metrics(aggregator, services)
+
+
 @pytest.mark.e2e
 def test_basic_e2e(dd_agent_check, check, instance_basic):
     aggregator = dd_agent_check(instance_basic)