[nutanix] Normalize ntnx_* tags to lowercase with $unknown fallback (DataDog#23609)

* fix(nutanix): normalize all ntnx_* tags to lowercase with $unknown fallback

Route every enum-backed ntnx_* tag (host_type, hypervisor_type,
node_status, plus the previously-handled state tags) through a single
_norm_state helper so they all follow one rule: lowercase the API
value, fall back to "\$unknown" when the source is missing.

Picks "\$unknown" (the API spec's own sentinel) as the fallback so
there's no mismatch between "value present but says \$UNKNOWN" and
"value missing" — both surface as ntnx_X:\$unknown.

ntnx_disk_status's "unknown" fallback is updated to "\$unknown" for
the same reason.

* docs(nutanix): add changelog for tag normalization

* docs(nutanix): shorten changelog to one customer-facing line

* refactor(nutanix): extract tag values into named variables

Hoist _norm_state and get_nested calls out of f-strings in the
tag-extraction helpers. Each tag computation now binds to a named
local first, making the read top-down and easier to step through.

* refactor(nutanix): rename _norm_state to _normalize_tag_value

The helper is used for type, state, mode, and status tags — not just
state — so the broader name better describes what it does.

* refactor(nutanix): collapse node_status to one variable, restore tags = []

Lowercase the node-status comparison sets so the normalized tag value
serves both the status_value lookup and the tag emission, removing the
need for a separate node_status_tag local.

Restore the tags = [] preamble in the tag-extraction helpers since it
makes the building intent obvious.

* fix(nutanix): normalize powerState in vm.status gauge

Match what _report_host_status_metrics does: route the powerState
lookup through _normalize_tag_value and lowercase the comparison
literals. Removes the asymmetry where vm.status was the only metric
still relying on raw uppercase API values.

Addresses review feedback on PR DataDog#23609.

* refactor(nutanix): normalize disk statuses in _aggregate_disk_status

Lowercase DEGRADED_DISK_STATUSES at the constant and route disk
``status`` values through ``_normalize_tag_value`` so the comparison
surface matches the rest of the module. Aligns with the convention
introduced in ``_report_host_status_metrics``.

* test(nutanix): cover \$unknown fallback for host enum tags

Verify ``ntnx_host_type``, ``ntnx_hypervisor_type``, and
``ntnx_node_status`` emit ``\$unknown`` when ``hostType``,
``hypervisor.type``, and ``nodeStatus`` are absent from the host
payload, the always-emit behavior introduced in this PR.

* test(nutanix): align unknown-fallback test with repo conventions

Author: NouemanKHAL

nutanix/changelog.d/23609.fixed

@@ -0,0 +1 @@
+Always emit `ntnx_host_type`, `ntnx_hypervisor_type`, and `ntnx_node_status` tags, with `$unknown` as the fallback when the source field is missing.

nutanix/datadog_checks/nutanix/infrastructure_monitor.py

@@ -23,16 +23,9 @@
     from datadog_checks.nutanix.check import NutanixCheck
 
 
-# Sentinel values from the Nutanix v4.0 specs that should be treated as unknown.
-_SENTINEL_STATE_VALUES = frozenset({"$unknown", "$redacted", "undetermined"})
-
-
-def _norm_state(value: object) -> str:
-    """Lowercase ``value``, mapping spec sentinels and missing values to ``unknown``."""
-    if not isinstance(value, str) or not value:
-        return "unknown"
-    normalized = value.lower()
-    return "unknown" if normalized in _SENTINEL_STATE_VALUES else normalized
+def _normalize_tag_value(value: object) -> str:
+    """Lowercase ``value``; missing values fall back to ``$unknown`` (the API's spec sentinel)."""
+    return value.lower() if isinstance(value, str) and value else "$unknown"
 
 
 @dataclass
@@ -245,8 +238,8 @@ def _report_vm_basic_metrics(self, vm: dict, hostname: str, vm_tags: list[str])
         """Report basic VM metrics (counts and status)."""
         self.check.gauge("vm.count", 1, hostname=hostname, tags=vm_tags)
 
-        power_state = vm.get("powerState", "$UNKNOWN")
-        status_value = 0 if power_state == "ON" else 1 if power_state == "PAUSED" else 2
+        power_state = _normalize_tag_value(vm.get("powerState"))
+        status_value = 0 if power_state == "on" else 1 if power_state == "paused" else 2
         self.check.gauge("vm.status", status_value, hostname=hostname, tags=vm_tags)
 
         self._report_vm_capacity_metrics(vm, hostname, vm_tags)
@@ -477,10 +470,10 @@ def _report_host_capacity_metrics(self, host: dict, hostname: str, host_tags: li
 
     def _report_host_status_metrics(self, host: dict, hostname: str, host_tags: list[str]) -> None:
         """Report host node status as a gauge (0=OK, 1=WARNING, 2=CRITICAL/UNKNOWN)."""
-        node_status_ok = {"NORMAL", "NEW_NODE", "PREPROTECTED"}
-        node_status_warning = {"TO_BE_PREPROTECTED", "TO_BE_REMOVED", "OK_TO_BE_REMOVED"}
+        node_status_ok = {"normal", "new_node", "preprotected"}
+        node_status_warning = {"to_be_preprotected", "to_be_removed", "ok_to_be_removed"}
 
-        node_status = host.get("nodeStatus", "$UNKNOWN")
+        node_status = _normalize_tag_value(host.get("nodeStatus"))
 
         if node_status in node_status_ok:
             status_value = 0
@@ -494,70 +487,59 @@ def _report_host_status_metrics(self, host: dict, hostname: str, host_tags: list
 
     def _extract_host_tags(self, host: dict) -> list[str]:
         """Extract tags from a host object."""
-        tags = []
+        host_name = host.get("hostName")
+        host_type = _normalize_tag_value(host.get("hostType"))
+        maintenance_state = _normalize_tag_value(host.get("maintenanceState"))
+        hypervisor_name = get_nested(host, "hypervisor/fullName")
+        hypervisor_type = _normalize_tag_value(get_nested(host, "hypervisor/type"))
+        connection_state = _normalize_tag_value(get_nested(host, "hypervisor/acropolisConnectionState"))
 
+        tags = []
         tags.append("ntnx_type:host")
-
-        if host_name := host.get("hostName"):
+        if host_name:
             tags.append(f"ntnx_host_name:{host_name}")
-
-        if host_type := host.get("hostType"):
-            tags.append(f"ntnx_host_type:{host_type}")
-
-        tags.append(f"ntnx_maintenance_state:{_norm_state(host.get('maintenanceState'))}")
-
-        # hypervisor tags
-        if hypervisor_name := get_nested(host, "hypervisor/fullName"):
+        tags.append(f"ntnx_host_type:{host_type}")
+        tags.append(f"ntnx_maintenance_state:{maintenance_state}")
+        if hypervisor_name:
             tags.append(f"ntnx_hypervisor_name:{hypervisor_name}")
-        if hypervisor_type := get_nested(host, "hypervisor/type"):
-            tags.append(f"ntnx_hypervisor_type:{hypervisor_type}")
-        tags.append(f"ntnx_connection_state:{_norm_state(get_nested(host, 'hypervisor/acropolisConnectionState'))}")
-
-        # Add category tags
+        tags.append(f"ntnx_hypervisor_type:{hypervisor_type}")
+        tags.append(f"ntnx_connection_state:{connection_state}")
         tags.extend(self.check.extract_category_tags(host))
 
         return tags
 
     def _extract_cluster_tags(self, cluster: dict) -> list[str]:
         """Extract tags from a cluster object."""
-        tags = []
-
         cluster_name = cluster.get("name")
+        operation_mode = _normalize_tag_value(get_nested(cluster, "config/operationMode"))
+
+        tags = []
         if cluster_name:
             tags.append(f"ntnx_cluster_name:{cluster_name}")
-
-        tags.append(f"ntnx_operation_mode:{_norm_state(get_nested(cluster, 'config/operationMode'))}")
-
-        # Add category tags
+        tags.append(f"ntnx_operation_mode:{operation_mode}")
         tags.extend(self.check.extract_category_tags(cluster))
 
         return tags
 
     def _extract_vm_tags(self, vm: dict) -> list[str]:
         """Extract tags from a VM object."""
-        tags = []
+        vm_name = vm.get("name")
+        host_id = get_nested(vm, "host/extId")
+        cluster_id = get_nested(vm, "cluster/extId")
+        is_agent_vm = is_affirmative(vm.get("isAgentVm"))
+        power_state = _normalize_tag_value(vm.get("powerState"))
 
+        tags = []
         tags.append("ntnx_type:vm")
-
-        vm_name = vm.get("name")
         if vm_name:
             tags.append(f"ntnx_vm_name:{vm_name}")
-
-        # Add category tags
         tags.extend(self.check.extract_category_tags(vm))
-
-        host_id = get_nested(vm, "host/extId")
         if host_id and host_id in self.host_names:
             tags.append(f"ntnx_host_name:{self.host_names[host_id]}")
-
-        cluster_id = get_nested(vm, "cluster/extId")
         if cluster_id and cluster_id in self.cluster_names:
             tags.append(f"ntnx_cluster_name:{self.cluster_names[cluster_id]}")
-
-        is_agent_vm = is_affirmative(vm.get("isAgentVm"))
         tags.append(f"ntnx_is_agent_vm:{is_agent_vm}")
-
-        tags.append(f"ntnx_power_state:{_norm_state(vm.get('powerState'))}")
+        tags.append(f"ntnx_power_state:{power_state}")
 
         return tags
 
@@ -623,18 +605,19 @@ def _build_disks_by_host_cache(self) -> None:
                 self._disks_by_host.setdefault(node_id, []).append(disk)
 
     def _aggregate_disk_status(self, disks: list[dict]) -> str:
-        """Return the worst disk status across ``disks``: degraded > normal > unknown."""
-        statuses = {d.get("status") for d in disks if d.get("status")}
+        """Return the worst disk status across ``disks``: degraded > normal > $unknown."""
+        statuses = {_normalize_tag_value(d.get("status")) for d in disks if d.get("status")}
         if statuses & DEGRADED_DISK_STATUSES:
             return "degraded"
-        if "NORMAL" in statuses:
+        if "normal" in statuses:
             return "normal"
-        return "unknown"
+        return "$unknown"
 
     def _get_disk_status_storage_tags(self, host_id: str) -> dict[str, list[str]]:
         """Return per-key extra tags adding ``ntnx_disk_status`` on host storage_* metrics."""
         status = self._aggregate_disk_status(self._disks_by_host.get(host_id, []))
-        return {key: [f"ntnx_disk_status:{status}"] for key in HOST_STORAGE_STAT_KEYS}
+        disk_status_tag = f"ntnx_disk_status:{status}"
+        return {key: [disk_status_tag] for key in HOST_STORAGE_STAT_KEYS}
 
     def _build_stats_params(self) -> dict[str, str | int]:
         """Build the common query parameters for stats API calls."""

nutanix/datadog_checks/nutanix/metrics.py

@@ -16,9 +16,9 @@
 # Disk status enum values that aggregate to ntnx_disk_status:degraded.
 DEGRADED_DISK_STATUSES: frozenset[str] = frozenset(
     {
-        "MARKED_FOR_REMOVAL_BUT_NOT_DETACHABLE",
-        "DATA_MIGRATION_INITIATED",
-        "DETACHABLE",
+        "marked_for_removal_but_not_detachable",
+        "data_migration_initiated",
+        "detachable",
     }
 )
 

nutanix/tests/constants.py

@@ -29,9 +29,9 @@
     'ntnx_cluster_name:datadog-nutanix-dev',
     'ntnx_connection_state:connected',
     'ntnx_host_name:10-0-0-103-aws-us-east-1a',
-    'ntnx_host_type:HYPER_CONVERGED',
+    'ntnx_host_type:hyper_converged',
     'ntnx_hypervisor_name:AHV 10.3',
-    'ntnx_hypervisor_type:AHV',
+    'ntnx_hypervisor_type:ahv',
     'ntnx_maintenance_state:normal',
     'ntnx_operation_mode:normal',
     'ntnx_type:host',

nutanix/tests/test_disk_status.py

@@ -22,7 +22,7 @@ def test_disks_endpoint_failure_falls_back_to_unknown(dd_run_check, aggregator,
     aggregator.assert_metric(
         "nutanix.host.storage_capacity",
         at_least=1,
-        tags=HOST_TAGS + ['ntnx_disk_status:unknown'],
+        tags=HOST_TAGS + ['ntnx_disk_status:$unknown'],
         hostname=HOST_NAME,
     )
 

nutanix/tests/test_hosts.py

@@ -46,7 +46,51 @@ def test_host_status_metrics(dd_run_check, aggregator, mock_instance, mock_http_
     dd_run_check(check)
 
     aggregator.assert_metric(
-        "nutanix.host.status", value=0, tags=HOST_TAGS + ['ntnx_node_status:NORMAL'], hostname=HOST_NAME
+        "nutanix.host.status", value=0, tags=HOST_TAGS + ['ntnx_node_status:normal'], hostname=HOST_NAME
+    )
+
+
+def test_host_tags_fall_back_to_unknown_when_source_fields_missing(
+    dd_run_check, aggregator, mock_instance, mock_http_get, mocker
+):
+    """When hostType, hypervisor.type, or nodeStatus are missing, tags emit ``$unknown``."""
+    cluster_id = "00064715-c043-5d8f-ee4b-176ec875554d"
+    sparse_host = {
+        "extId": "d8787814-4fe8-4ba5-931f-e1ee31c294a6",
+        "hostName": HOST_NAME,
+        "hypervisor": {"fullName": "AHV 10.3"},
+        "cluster": {"uuid": cluster_id},
+    }
+    mocker.patch(
+        "datadog_checks.nutanix.infrastructure_monitor.InfrastructureMonitor._list_hosts_by_cluster",
+        side_effect=lambda cid: [sparse_host] if cid == cluster_id else [],
+    )
+    check = NutanixCheck('nutanix', {}, [mock_instance])
+    dd_run_check(check)
+
+    expected_tags = [
+        'Team:agent-integrations',
+        'cluster_category:cluster_value1',
+        'cluster_category:cluster_value2',
+        'cluster_category:cluster_value3',
+        'ntnx_cluster_name:datadog-nutanix-dev',
+        'ntnx_connection_state:$unknown',
+        f'ntnx_host_name:{HOST_NAME}',
+        'ntnx_host_type:$unknown',
+        'ntnx_hypervisor_name:AHV 10.3',
+        'ntnx_hypervisor_type:$unknown',
+        'ntnx_maintenance_state:$unknown',
+        'ntnx_operation_mode:normal',
+        'ntnx_type:host',
+        'nutanix',
+        'prism_central:10.0.0.197',
+    ]
+    aggregator.assert_metric("nutanix.host.count", value=1, tags=expected_tags, hostname=HOST_NAME)
+    aggregator.assert_metric(
+        "nutanix.host.status",
+        value=2,
+        tags=expected_tags + ['ntnx_node_status:$unknown'],
+        hostname=HOST_NAME,
     )