Add lparstats check (AIX only) (DataDog#23451)

* Add lparstats check (AIX only)

Port the lparstats check from datadog-unix-agent to integrations-core,
updated for Python 3 and datadog-checks-base.

This check collects IBM POWER LPAR performance metrics on AIX via the
`lparstat` command:
- Memory statistics (system.lpar.memory.*)
- Hypervisor call statistics (system.lpar.hypervisor.*)
- I/O memory entitlements (system.lpar.memory.entitlement.*)
- SPURR processor utilization (system.lpar.spurr.*)

The manifest explicitly declares "Supported OS::AIX" as this check
relies on lparstat which is exclusive to IBM AIX on POWER hardware.

* Fix validation issues: license headers, CHANGELOG, metadata sort, spec.yaml, labeler, ci

* Generate config models, sync conf.yaml.example, sync CI, fix lint

* Add missing [project.optional-dependencies] section to pyproject.toml

* Add basic unit tests with mocked lparstat output

* Fix test: remove dd_environment fixture (no Docker needed)

* Remove unused pytest import

* Fix test: remove assert_all_metrics_covered, check key metrics only

* Add dd_environment fixture and rebase onto master

* Fix manifest: remove invalid Supported OS::AIX tag, add auto_install and source_type_id

* Apply review nits: f-strings, x.split(), hypervisor guard, dev status 5, remove setup.cfg, skip e2e on non-AIX

* lparstats: declare SPURR .pct metrics as fraction not percent

Values emitted by collect_spurr are in the [0,1] range (e.g. 0.015),
not [0,100], so unit_name=percent was incorrect.

* lparstats: set curated_metric=core for system.lpar.memory.physb

This is the manifest's primary check metric; marking it as core aligns
with the convention used by other integrations.

* lparstats: always apply DEFAULT_TIMEOUT, not only under sudo

A hung lparstat call can block the check regardless of whether sudo is
in use; unconditionally setting the timeout is the safer default.

* lparstats: strip % from field names in collect_memory_entitlements

collect_memory already strips % from its fields; apply the same
treatment in collect_memory_entitlements so a %-suffixed column in
lparstat -m -eR output produces a valid metric name.

* lparstats: add type hints to all callables

* lparstats: replace HYPERVISOR_IDX_METRIC_MAP dict with a tuple

Contiguous integer keys 0..4 are just positional indices; a tuple
is simpler and removes the need for a dict-lookup pattern.

* lparstats: patch subprocess.run in tests instead of private _run_cmd

Coupling tests to the internal _run_cmd helper is fragile; patching the
public subprocess.run interface is more stable and matches the project
testing guidelines.

* lparstats: use dd_run_check fixture instead of check.check(instance)

* lparstats: add tests for hypervisor and memory-entitlements collectors

Both collectors had zero coverage because the default instance fixture
disables them. Add a dedicated test that enables both and asserts that
expected metrics are emitted.

* lparstats: add tag assertions for all collectors

Assert that memory/SPURR metrics carry no tags and that hypervisor
(call:<name>) and entitlement (iompn:<name>) tags are present.

* lparstats: guard os.getuid() with hasattr check

os.getuid() does not exist on Windows; wrap it so the module can be
imported on non-Unix platforms without raising AttributeError.

* lparstats: check returncode in all collectors, add lparstats.can_collect service check

Each collector now inspects the lparstat return code and skips metric
emission (with a warning) on failure instead of silently parsing empty
output. A new lparstats.can_collect service check is emitted OK when
all enabled collectors succeed and CRITICAL if any lparstat invocation
exits non-zero.

* lparstats: fix fragile SPURR actual-vs-normalized column split

The previous split used idx > len(fields)/2, which silently breaks if
lparstat -E ever changes its column count. Split at the freq column
instead (it reliably separates actual from normalized), with a fallback
warning if freq is absent.

* lparstats: extract _lparstat_rows helper to deduplicate parsing prefix

All four collectors shared the same _run_cmd → splitlines → filter →
slice pattern. _lparstat_rows(cmd, start_idx, ...) centralises it and
returns (rows, stderr, returncode) so callers can still inspect the
exit code.

* lparstats: fix curated_metric value for system.lpar.memory.physb

Valid values are cpu and memory; core is not accepted by the validator.

* lparstats: disable e2e env, remove dd_environment fixture

Set e2e-env = false in hatch.toml so CI does not try to spin up an
e2e environment for an AIX-only check that can never run on Linux CI.
Remove the now-redundant dd_environment fixture from conftest.py.

* lparstats: set owner to agent-integrations

Author: pgimalac

.codecov.yml

@@ -430,6 +430,10 @@ coverage:
         target: 75
         flags:
         - kyototycoon
+      LPARStats:
+        target: 75
+        flags:
+        - lparstats
       Lighttpd:
         target: 75
         flags:
@@ -1408,6 +1412,11 @@ flags:
     paths:
     - kyverno/datadog_checks/kyverno
     - kyverno/tests
+  lparstats:
+    carryforward: true
+    paths:
+    - lparstats/datadog_checks/lparstats
+    - lparstats/tests
   lighttpd:
     carryforward: true
     paths:

.github/workflows/config/labeler.yml

@@ -890,6 +890,10 @@ integration/langchain:
 - changed-files:
   - any-glob-to-any-file:
     - langchain/**/*
+integration/lparstats:
+- changed-files:
+  - any-glob-to-any-file:
+    - lparstats/**/*
 integration/lastpass:
 - changed-files:
   - any-glob-to-any-file:

.github/workflows/test-all.yml

@@ -2457,6 +2457,26 @@ jobs:
       minimum-base-package: ${{ inputs.minimum-base-package }}
       pytest-args: ${{ inputs.pytest-args }}
     secrets: inherit
+  jefcf576:
+    uses: ./.github/workflows/test-target.yml
+    with:
+      job-name: LPARStats
+      target: lparstats
+      platform: linux
+      runner: '["ubuntu-22.04"]'
+      repo: "${{ inputs.repo }}"
+      context: ${{ inputs.context }}
+      python-version: "${{ inputs.python-version }}"
+      latest: ${{ inputs.latest }}
+      agent-image: "${{ inputs.agent-image }}"
+      agent-image-py2: "${{ inputs.agent-image-py2 }}"
+      agent-image-windows: "${{ inputs.agent-image-windows }}"
+      agent-image-windows-py2: "${{ inputs.agent-image-windows-py2 }}"
+      test-py2: ${{ inputs.test-py2 }}
+      test-py3: ${{ inputs.test-py3 }}
+      minimum-base-package: ${{ inputs.minimum-base-package }}
+      pytest-args: ${{ inputs.pytest-args }}
+    secrets: inherit
   je63e92c:
     uses: ./.github/workflows/test-target.yml
     with:

lparstats/CHANGELOG.md

@@ -0,0 +1,3 @@
+# CHANGELOG - lparstats
+
+<!-- towncrier release notes start -->

lparstats/README.md

@@ -0,0 +1,71 @@
+# LPARStats
+
+## Overview
+
+The LPARStats check collects performance metrics from IBM POWER Logical Partitions (LPARs)
+running AIX by parsing the output of the `lparstat` command.
+
+**This check is only supported on AIX.** It relies on the `lparstat` utility, which is
+exclusive to IBM AIX on POWER hardware.
+
+Metrics collected:
+
+- **Memory statistics** (`system.lpar.memory.*`): physical memory usage, page statistics,
+  I/O memory pool utilization.
+- **Hypervisor call statistics** (`system.lpar.hypervisor.*`): per-call counts and latency
+  for hypervisor calls. Requires root or sudo.
+- **I/O memory entitlements** (`system.lpar.memory.entitlement.*`): per-pool entitlement
+  and allocation data. Requires root or sudo.
+- **SPURR processor utilization** (`system.lpar.spurr.*`): actual and normalized physical
+  processor utilization rates.
+
+## Setup
+
+### Installation
+
+The LPARStats check is included in the [Datadog Agent][1] package for AIX. No additional
+installation is needed.
+
+### Configuration
+
+1. Edit the `lparstats.d/conf.yaml` file in your Agent's `conf.d/` directory.
+   See the [sample lparstats.d/conf.yaml][2] for all available configuration options.
+
+2. To collect hypervisor and memory entitlement metrics, the Agent must run as root, or
+   the `dd-agent` user must be granted sudo access to `lparstat`:
+
+   ```
+   dd-agent ALL=(root) NOPASSWD: /usr/bin/lparstat
+   ```
+
+3. [Restart the Agent][3].
+
+### Validation
+
+Run the [Agent's status subcommand][4] and look for `lparstats` under the Checks section.
+
+## Data Collected
+
+### Metrics
+
+See [metadata.csv][5] for a list of metrics provided by this check.
+
+### Service Checks
+
+`lparstats.can_collect`
+: Returns `CRITICAL` if any `lparstat` sub-command exits with a non-zero return code. Returns `OK` otherwise.
+
+### Events
+
+The LPARStats check does not include any events.
+
+## Support
+
+Need help? Contact [Datadog support][6].
+
+[1]: https://app.datadoghq.com/account/settings/agent/latest
+[2]: https://github.com/DataDog/integrations-core/blob/master/lparstats/datadog_checks/lparstats/data/conf.yaml.example
+[3]: https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent
+[4]: https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information
+[5]: https://github.com/DataDog/integrations-core/blob/master/lparstats/metadata.csv
+[6]: https://docs.datadoghq.com/help/

lparstats/assets/configuration/spec.yaml

@@ -0,0 +1,61 @@
+name: LPARStats
+files:
+- name: lparstats.yaml
+  options:
+  - template: init_config
+    options:
+    - template: init_config/default
+  - template: instances
+    options:
+    - name: name
+      description: A name for this instance.
+      required: false
+      value:
+        type: string
+        example: lparstats
+    - name: sudo
+      description: |
+        Run lparstat with sudo. Requires adding dd-agent to the sudoers file:
+
+          dd-agent ALL=(ALL) NOPASSWD: /usr/bin/lparstat
+
+        When running as root, sudo is not needed.
+      required: false
+      value:
+        type: boolean
+        example: false
+    - name: memory_stats
+      description: Collect physical memory and page statistics (lparstat -m).
+      required: false
+      value:
+        type: boolean
+        example: true
+    - name: page_stats
+      description: Include page-level statistics (-pw flag). Requires memory_stats to be true.
+      required: false
+      value:
+        type: boolean
+        example: true
+    - name: memory_entitlements
+      description: |
+        Collect per-I/O-memory-pool entitlement stats (lparstat -m -eR).
+        Requires root or sudo.
+      required: false
+      value:
+        type: boolean
+        example: true
+    - name: hypervisor
+      description: |
+        Collect hypervisor call statistics (lparstat -H).
+        Requires root or sudo.
+      required: false
+      value:
+        type: boolean
+        example: true
+    - name: spurr_utilization
+      description: Collect SPURR physical processor utilization (lparstat -E).
+      required: false
+      value:
+        type: boolean
+        example: true
+    - template: instances/default

lparstats/assets/service_checks.json

@@ -0,0 +1,11 @@
+[
+    {
+        "agent_version": "7.0.0",
+        "integration": "lparstats",
+        "check": "lparstats.can_collect",
+        "statuses": ["ok", "critical"],
+        "groups": [],
+        "name": "LPARStats Can Collect",
+        "description": "Returns `CRITICAL` if any `lparstat` sub-command fails (non-zero exit code). Returns `OK` otherwise."
+    }
+]

lparstats/datadog_checks/lparstats/__about__.py

@@ -0,0 +1,5 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+__version__ = '0.1.0'

lparstats/datadog_checks/lparstats/__init__.py

@@ -0,0 +1,8 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+from .__about__ import __version__
+from .lparstats import LPARStats
+
+__all__ = ['__version__', 'LPARStats']

lparstats/datadog_checks/lparstats/config_models/__init__.py

@@ -0,0 +1,24 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+# This file is autogenerated.
+# To change this file you should edit assets/configuration/spec.yaml and then run the following commands:
+#     ddev -x validate config -s <INTEGRATION_NAME>
+#     ddev -x validate models -s <INTEGRATION_NAME>
+
+from .instance import InstanceConfig
+from .shared import SharedConfig
+
+
+class ConfigMixin:
+    _config_model_instance: InstanceConfig
+    _config_model_shared: SharedConfig
+
+    @property
+    def config(self) -> InstanceConfig:
+        return self._config_model_instance
+
+    @property
+    def shared_config(self) -> SharedConfig:
+        return self._config_model_shared