[AI-5554] Add support for submitting events for proxmox tasks (#20849)

sarah-witt · NouemanKHAL · web-flow · commit acd46b59e964 · 2025-07-31T18:58:31.000Z
* Add support for tasks as events

* Add changelog

* fix

* test

* fix timezon

* Add event categories

* address comments

* Address comments

* Update proxmox/tests/test_unit.py

Co-authored-by: NouemanKHAL &lt;noueman.khalikine@datadoghq.com&gt;

* Address

* Update proxmox/tests/test_unit.py

Co-authored-by: NouemanKHAL &lt;noueman.khalikine@datadoghq.com&gt;

---------

Co-authored-by: NouemanKHAL &lt;noueman.khalikine@datadoghq.com&gt;
diff --git a/proxmox/assets/configuration/spec.yaml b/proxmox/assets/configuration/spec.yaml
@@ -16,6 +16,39 @@ files:
         example: http://localhost:8006/api2/json
         type: string
       required: true
+    - name: collect_tasks
+      display_priority: 5
+      description: |
+        Whether or not to collect Proxmox tasks as events.
+      value:
+        type: boolean
+        example: true
+        display_default: false
+      required: false
+    - name: collected_task_types
+      display_priority: 5
+      description: |
+        Which Proxmox task types to collect. When `collect_tasks` is enabled, the integration will collect
+        the following task types by default:
+          - qmstart
+          - qhstop
+          - qmshutdown
+          - qmreboot
+          - qmigrate
+          - qmsuspend
+          - vzstart
+          - vzshutdown
+          - vzsuspend
+          - startall
+          - stopall
+          - suspendall
+          - aptupdate
+      value:
+        type: array
+        items:
+          type: string
+        default: ['qmstart', 'qmstop', 'qmshutdown', 'qmreboot', 'qmigrate', 'qmsuspend', 'vzstart', 'vzshutdown', 'vzsuspend', 'startall', 'stopall', 'suspendall', 'aptupdate']
+      required: false
     - template: instances/default
       overrides:
         empty_default_hostname.display_priority: 1
diff --git a/proxmox/changelog.d/20849.added b/proxmox/changelog.d/20849.added
@@ -0,0 +1 @@
+Add support for sending tasks as events.
diff --git a/proxmox/datadog_checks/proxmox/check.py b/proxmox/datadog_checks/proxmox/check.py
@@ -1,12 +1,15 @@
 # (C) Datadog, Inc. 2025-present
 # All rights reserved
 # Licensed under a 3-clause BSD style license (see LICENSE)
+
 from requests.exceptions import ConnectionError, HTTPError, InvalidURL, JSONDecodeError, Timeout
 
 from datadog_checks.base import AgentCheck
+from datadog_checks.base.utils.time import get_current_datetime, get_timestamp
 from datadog_checks.proxmox.config_models import ConfigMixin
 
 from .constants import (
+    EVENT_TYPE_TO_TITLE,
     NODE_RESOURCE,
     OK_STATUS,
     PERF_METRIC_NAME,
@@ -17,13 +20,22 @@
 )
 
 
+def resource_type_for_event_type(event_type):
+    if event_type.startswith('vz'):
+        return 'lxc'
+    elif event_type.startswith('qm') or event_type.startswith('vnc'):
+        return 'qemu'
+    return 'node'
+
+
 class ProxmoxCheck(AgentCheck, ConfigMixin):
     __NAMESPACE__ = 'proxmox'
 
     def __init__(self, name, init_config, instances):
         super(ProxmoxCheck, self).__init__(name, init_config, instances)
-        self.check_initializations.append(self._parse_config)
         self.all_resources = {}
+        self.last_event_collect_time = get_current_datetime()
+        self.check_initializations.append(self._parse_config)
 
     def _parse_config(self):
         self.base_tags = [f"proxmox_server:{self.config.proxmox_server}"]
@@ -54,6 +66,49 @@ def _get_vm_hostname(self, vm_id, vm_name, node):
         hostname = hostname_json.get("data", {}).get("result", {}).get("host-name", vm_name)
         return hostname
 
+    def _create_dd_event_for_task(self, task, node_name):
+        task_type = task.get('type')
+        status = "success" if task.get("status") == "OK" else "error"
+        id = task.get('id') if task.get('id') else node_name
+        user = task.get('user')
+        event_title = EVENT_TYPE_TO_TITLE.get(task_type, task_type)
+        resource_type = resource_type_for_event_type(task_type)
+        resource_id = f'{resource_type}/{id}'
+        self.log.debug(
+            "Creating event for task type: %s ID: %s, resource id %s on node %s",
+            task_type,
+            id,
+            resource_id,
+            node_name,
+        )
+
+        resource = self.all_resources.get(resource_id, {})
+
+        tags = list(resource.get('tags', []))
+        tags.append(f'proxmox_event_type:{task_type}')
+        tags.append(f'proxmox_user:{user}')
+
+        timestamp = task.get('endtime', get_timestamp(get_current_datetime()))
+        hostname = resource.get('hostname', None)
+
+        if resource_type != 'node':
+            resource_type_format = resource.get('resource_type', 'node').capitalize()
+            event_message = f"{resource_type_format} {resource.get('resource_name')}: {event_title} on node {node_name}"
+        else:
+            event_message = f"{event_title} on node {node_name}"
+
+        event = {
+            'timestamp': timestamp,
+            'event_type': self.__NAMESPACE__,
+            'host': hostname,
+            'msg_text': event_message,
+            'msg_title': event_title,
+            'alert_type': status,
+            'source_type_name': self.__NAMESPACE__,
+            'tags': tags,
+        }
+        return event
+
     def _collect_ha_metrics(self):
         ha_response = self.http.get(f"{self.config.proxmox_server}/cluster/ha/status/current")
         ha_response_json = ha_response.json()
@@ -155,7 +210,12 @@ def _collect_resource_metrics(self):
             else:
                 external_tags.append((hostname, {self.__NAMESPACE__: self.base_tags + list(resource_tags)}))
 
-            all_resources[resource_id] = {'resource_type': resource_type_remapped, 'tags': tags, 'hostname': hostname}
+            all_resources[resource_id] = {
+                'resource_type': resource_type_remapped,
+                'resource_name': resource_name,
+                'tags': tags,
+                'hostname': hostname,
+            }
 
             if resource_type_remapped != "pool":
                 # pools don't have a status attribute
@@ -170,6 +230,33 @@ def _collect_resource_metrics(self):
         self.all_resources = all_resources
         self.set_external_tags(external_tags)
 
+    def _collect_tasks(self):
+        for resource in self.all_resources.values():
+            if resource.get('resource_type') != 'node':
+                continue
+
+            node_name = resource.get('hostname')
+            since = int(get_timestamp(self.last_event_collect_time))
+            self.log.debug("Collecting events for node %s since %s", node_name, since)
+
+            now = get_current_datetime()
+            params = {'since': since}
+            response = self.http.get(f"{self.config.proxmox_server}/nodes/{node_name}/tasks", params=params)
+            response.raise_for_status()
+
+            response_json = response.json().get("data", [])
+            self.last_event_collect_time = now
+
+            for task in response_json:
+                task_type = task.get('type')
+
+                if task_type not in self.config.collected_task_types:
+                    continue
+
+                event = self._create_dd_event_for_task(task, node_name)
+                self.log.debug("Submitting event %s", event)
+                self.event(event)
+
     def check(self, _):
         try:
             response = self.http.get(f"{self.config.proxmox_server}/version")
@@ -190,3 +277,5 @@ def check(self, _):
         self._collect_resource_metrics()
         self._collect_performance_metrics()
         self._collect_ha_metrics()
+        if self.config.collect_tasks:
+            self._collect_tasks()
diff --git a/proxmox/datadog_checks/proxmox/config_models/defaults.py b/proxmox/datadog_checks/proxmox/config_models/defaults.py
@@ -24,6 +24,28 @@ def instance_auth_type():
     return 'basic'
 
 
+def instance_collect_tasks():
+    return False
+
+
+def instance_collected_task_types():
+    return [
+        'qmstart',
+        'qmstop',
+        'qmshutdown',
+        'qmreboot',
+        'qmigrate',
+        'qmsuspend',
+        'vzstart',
+        'vzshutdown',
+        'vzsuspend',
+        'startall',
+        'stopall',
+        'suspendall',
+        'aptupdate',
+    ]
+
+
 def instance_disable_generic_tags():
     return False
 
diff --git a/proxmox/datadog_checks/proxmox/config_models/instance.py b/proxmox/datadog_checks/proxmox/config_models/instance.py
@@ -60,6 +60,8 @@ class InstanceConfig(BaseModel):
     aws_host: Optional[str] = None
     aws_region: Optional[str] = None
     aws_service: Optional[str] = None
+    collect_tasks: Optional[bool] = None
+    collected_task_types: Optional[tuple[str, ...]] = None
     connect_timeout: Optional[float] = None
     disable_generic_tags: Optional[bool] = None
     empty_default_hostname: Optional[bool] = None
diff --git a/proxmox/datadog_checks/proxmox/constants.py b/proxmox/datadog_checks/proxmox/constants.py
@@ -46,3 +46,20 @@
 }
 
 RESOURCE_COUNT_METRICS = ['uptime']
+
+EVENT_TYPE_TO_TITLE = {
+    'vzstart': 'Container Started',
+    'vzshutdown': 'Container Shutdown',
+    'vzsuspend': 'Container Suspened',
+    'qmstart': 'VM Started',
+    'qhstop': 'VM Stopped',
+    'qmshutdown': 'VM Shutdown',
+    'qmreboot': 'VM Rebooted',
+    'qmigrate': 'VM Migrated',
+    'qmsuspend': 'VM Hibernated',
+    'startall': 'Bulk start VMs and Containers',
+    'stopall': 'Bulk stop VMs and Containers',
+    'suspendall': 'Bulk suspend VMs and Containers',
+    'aptupdate': 'Update package database',
+    'vncproxy': 'Console started',
+}
diff --git a/proxmox/datadog_checks/proxmox/data/conf.yaml.example b/proxmox/datadog_checks/proxmox/data/conf.yaml.example
@@ -50,6 +50,30 @@ instances:
     #
   - proxmox_server: http://localhost:8006/api2/json
 
+    ## @param collect_tasks - boolean - optional - default: false
+    ## Whether or not to collect Proxmox tasks as events.
+    #
+    # collect_tasks: true
+
+    ## @param collected_task_types - list of strings - optional
+    ## Which Proxmox task types to collect. When `collect_tasks` is enabled, the integration will collect
+    ## the following task types by default:
+    ##   - qmstart
+    ##   - qhstop
+    ##   - qmshutdown
+    ##   - qmreboot
+    ##   - qmigrate
+    ##   - qmsuspend
+    ##   - vzstart
+    ##   - vzshutdown
+    ##   - vzsuspend
+    ##   - startall
+    ##   - stopall
+    ##   - suspendall
+    ##   - aptupdate
+    #
+    # collected_task_types: []
+
     ## @param headers - mapping - optional
     ## Headers to use for every request. An Authorization header including the Proxmox API token is required
     ## for authentication for the REST API.
diff --git a/proxmox/manifest.json b/proxmox/manifest.json
@@ -18,11 +18,13 @@
       "Category::OS & System",
       "Category::Cloud",
       "Category::Network",
+      "Category::Event Management",
       "Category::Metrics",
       "Category::Log Collection",
       "Offering::Integration",
       "Submitted Data Type::Metrics",
-      "Submitted Data Type::Logs"
+      "Submitted Data Type::Logs",
+      "Submitted Data Type::Events"
     ]
   },
   "assets": {
diff --git a/proxmox/tests/common.py b/proxmox/tests/common.py
diff --git a/proxmox/tests/conftest.py b/proxmox/tests/conftest.py
diff --git a/proxmox/tests/fixtures/GET/api2/json/nodes/ip-122-82-3-112/tasks?since=1752552000/response.json b/proxmox/tests/fixtures/GET/api2/json/nodes/ip-122-82-3-112/tasks?since=1752552000/response.json
diff --git a/proxmox/tests/test_unit.py b/proxmox/tests/test_unit.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Add support for sending tasks as events.`