|
| 1 | +# Agent Check: Nutanix |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This check collects resource usage metrics from your Nutanix cluster, CPU, memory, storage, and I/O performance for clusters, hosts, and VMs. It also collects operational activity data from Prism Central, including events, tasks, audits, and alerts. |
| 6 | + |
| 7 | +## Setup |
| 8 | + |
| 9 | +### Installation |
| 10 | + |
| 11 | +The Nutanix check is included in the [Datadog Agent][1] package, so you don't need to install anything else on your server. |
| 12 | + |
| 13 | +### Configuration |
| 14 | + |
| 15 | +In Prism Central, create a user with the following roles: |
| 16 | + |
| 17 | +- Cluster Viewer |
| 18 | +- Virtual Machine Viewer |
| 19 | +- Prism Viewer |
| 20 | +- Monitoring Admin |
| 21 | + |
| 22 | +Then, edit the `nutanix.d/conf.yaml` file in the `conf.d/` folder at the root of your [Agent's configuration directory][2]. See the [sample nutanix.d/conf.yaml][3] for all available configuration options. |
| 23 | + |
| 24 | +A single Agent instance connected to Prism Central is enough to monitor all clusters, hosts, and VMs managed by that Prism Central. |
| 25 | + |
| 26 | +[Restart the Agent][4] to start sending Nutanix metrics and activity data to Datadog. |
| 27 | + |
| 28 | +**Note**: The default collection interval is 120 seconds. In practice, setting the interval to 60 seconds or higher results in more reliable and consistent metric collection. |
| 29 | + |
| 30 | +### Validation |
| 31 | + |
| 32 | +Run the [Agent's status subcommand][5] and look for `nutanix` under the Checks section. |
| 33 | + |
| 34 | +## Data Collected |
| 35 | + |
| 36 | +### Metrics |
| 37 | + |
| 38 | +See [metadata.csv][6] for a list of metrics provided by this check. |
| 39 | + |
| 40 | +The integration collects metrics across three resource types, each prefixed with its resource name: |
| 41 | + |
| 42 | +- **Cluster** (`nutanix.cluster.*`): storage capacity and usage, CPU and memory allocation, I/O performance, health score, VM counts. |
| 43 | +- **Host** (`nutanix.host.*`): per-host CPU, memory, storage, and controller I/O metrics. |
| 44 | +- **VM** (`nutanix.vm.*`): per-VM CPU, memory, disk, network, and storage tier metrics. |
| 45 | + |
| 46 | +A `nutanix.health.up` metric reports Prism Central connectivity status (`1` for reachable, `0` otherwise). |
| 47 | + |
| 48 | +#### Collecting activity data |
| 49 | + |
| 50 | +The integration collects operational activity data from Prism Central by default. Each activity type can be toggled independently in the `nutanix.d/conf.yaml` file: |
| 51 | + |
| 52 | +- `collect_events`: Prism Central events (default: `true`) |
| 53 | +- `collect_alerts`: alerts with severity information (default: `true`) |
| 54 | +- `collect_tasks`: infrastructure tasks, parent tasks only (default: `true`) |
| 55 | + - `collect_subtasks`: include subtasks alongside parent tasks (default: `false`) |
| 56 | +- `collect_audits`: user audit logs (default: `true`) |
| 57 | + |
| 58 | +### Events |
| 59 | + |
| 60 | +This check collects activity data from Prism Central and emits them as Datadog events. Each activity type is identified by the `ntnx_type` tag: |
| 61 | + |
| 62 | +- `ntnx_type:event`: Prism Central Events |
| 63 | +- `ntnx_type:alert`: Prism Central Alerts |
| 64 | +- `ntnx_type:task`: Prism Central Tasks |
| 65 | +- `ntnx_type:audit`: Prism Central Audits |
| 66 | + |
| 67 | +Use the `collect_events`, `collect_alerts`, `collect_tasks`, and `collect_audits` parameters in the [sample nutanix.d/conf.yaml][3] to toggle each activity type. |
| 68 | + |
| 69 | +**Note**: By default, only parent tasks are collected. Set `collect_subtasks: true` to include subtasks. |
| 70 | + |
| 71 | +### Service Checks |
| 72 | + |
| 73 | +The integration does not emit any service checks. |
| 74 | + |
| 75 | +## Troubleshooting |
| 76 | + |
| 77 | +### VM collection |
| 78 | + |
| 79 | +By default, only VMs with `powerState: ON` are collected. To collect VMs in other power states (OFF, PAUSED), add an explicit `powerState` VM filter in `resource_filters`: |
| 80 | + |
| 81 | +```yaml |
| 82 | +resource_filters: |
| 83 | + - resource: vm |
| 84 | + property: powerState |
| 85 | + patterns: |
| 86 | + - '.*' |
| 87 | +``` |
| 88 | +
|
| 89 | +Other VM filters (e.g., by name) do not override this default. Only a `powerState` filter does. |
| 90 | + |
| 91 | +### Category tags |
| 92 | + |
| 93 | +Nutanix categories are attached as tags to metrics. By default, only `USER` category tags are collected. To include `SYSTEM` or `INTERNAL` categories, add an explicit category filter in `resource_filters`. |
| 94 | + |
| 95 | +To collect `SYSTEM` and `INTERNAL` categories alongside `USER`: |
| 96 | + |
| 97 | +```yaml |
| 98 | +resource_filters: |
| 99 | + - resource: category |
| 100 | + property: type |
| 101 | + patterns: |
| 102 | + - '^SYSTEM$' |
| 103 | + - '^INTERNAL$' |
| 104 | + - '^USER$' |
| 105 | +``` |
| 106 | + |
| 107 | +Category tags use the Nutanix category key as the tag name (e.g., `Environment:Production`). Set `prefix_category_tags: true` to prefix them with `ntnx_` (e.g., `ntnx_Environment:Production`) to avoid collisions with existing Datadog tags. |
| 108 | + |
| 109 | +### Duplicate hostnames |
| 110 | + |
| 111 | +The Nutanix API does not expose the real hostname of VMs. VM metrics use the VM name from Prism Central as the hostname. If the Datadog Agent is installed on a Nutanix VM, its auto-detected hostname may differ from the VM name, causing duplicate hosts in Datadog. To fix this, set `hostname` in `datadog.yaml` (or the `DD_HOSTNAME` environment variable) to match the VM name in Prism Central. |
| 112 | + |
| 113 | +### Filtering resources |
| 114 | + |
| 115 | +Use the `resource_filters` option to control which resources are collected. Each filter requires a `resource` type, a `property` (the API field name to match against), and a list of regex `patterns`. Optionally, set `type` (`include` or `exclude`, default: `include`). Exclude filters take precedence over include filters. |
| 116 | + |
| 117 | +Supported resource types: `cluster`, `host`, `vm`, `event`, `task`, `alert`, `audit`, `category`. Nested properties are supported using `/` as a separator (e.g., `userReference/name`). Note that hosts use `hostName` as the API field for the host name, not `name`. |
| 118 | + |
| 119 | +```yaml |
| 120 | +resource_filters: |
| 121 | + - resource: cluster |
| 122 | + property: name |
| 123 | + patterns: |
| 124 | + - '^prod-' |
| 125 | + - resource: host |
| 126 | + property: hostName |
| 127 | + type: exclude |
| 128 | + patterns: |
| 129 | + - '^standby-' |
| 130 | + - resource: alert |
| 131 | + property: severity |
| 132 | + patterns: |
| 133 | + - '^WARNING$' |
| 134 | + - '^CRITICAL$' |
| 135 | +``` |
| 136 | + |
| 137 | +Need help? Contact [Datadog support][7]. |
| 138 | + |
| 139 | +[1]: https://app.datadoghq.com/account/settings/agent/latest |
| 140 | +[2]: https://docs.datadoghq.com/agent/guide/agent-configuration-files/#agent-configuration-directory |
| 141 | +[3]: https://github.com/DataDog/integrations-core/blob/master/nutanix/datadog_checks/nutanix/data/conf.yaml.example |
| 142 | +[4]: https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent |
| 143 | +[5]: https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information |
| 144 | +[6]: https://github.com/DataDog/integrations-core/blob/master/nutanix/metadata.csv |
| 145 | +[7]: https://docs.datadoghq.com/help/ |
0 commit comments