Registry / devops / genie-libs-health

genie-libs-health

JSON →
library26.5pypypiunverified

genie-libs-health is a Python library within the pyATS framework, providing a robust mechanism for monitoring network device health status. It allows users to define custom health checks using YAML files, which are then executed against devices configured in a pyATS testbed. This library is part of the `genie` ecosystem and is primarily used for automated network device validation and troubleshooting. It is currently at version `26.3` and follows the `genie` release cadence, which typically aligns with `pyATS` monthly releases.

pip install genie-libs-health
INSTALL
IMPORT
SIG · GENIE-LIBS-HEALTH
G
genie-libs-health
devopspythonv26.5
Install
36.3s avg
Import
Disk
685MB
Pass rate
7/ 10
Env Coverage7 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v26.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 34.8s
py 3.11
✕ build_error
✓ 33.85s
py 3.12
✕ build_error
✓ 36s
py 3.13
✕ build_error
✓ 34.8s
py 3.9
✓ —
✓ 42.25s
685MB installed
● package 685MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Health
from genie.libs.health import Health
from genie.libs.health import Health

This quickstart demonstrates how to define health checks using a YAML structure, initialize the `Health` object with a device (mocked for this example), and execute the checks. In a real scenario, `my_device` would be an actual connected device loaded from a pyATS testbed file. The example uses `unittest.mock` to make the code runnable without requiring actual device connectivity.

import yaml from unittest.mock import Mock # For a truly runnable example without a real device from genie.libs.health.health import Health # --- 1. Create a mock device and testbed for demonstration --- # In a real scenario, you would load a testbed from a file: # from pyats.topology import loader # testbed = loader.load('path/to/testbed.yaml') # my_device = testbed.devices['your_device_name'] # Mock a device and its connection/execution methods mock_device = Mock() mock_device.name = "my_mock_device" mock_device.os = "iosxe" mock_device.connected = False mock_device.api.execute.return_value = { "show version": "Cisco IOS XE Software, Version 17.3.4", "show processes cpu sorted": "CPU utilization for five seconds: 5%/1%; one minute: 4%; five minutes: 3%" } # Define connect/disconnect behavior for the mock def mock_connect(): print(f"Attempting to connect to {mock_device.name} (mocked)...") mock_device.connected = True print(f"Successfully connected to {mock_device.name} (mocked).") mock_device.connect.side_effect = mock_connect def mock_disconnect(): print(f"Disconnecting from {mock_device.name} (mocked)...") mock_device.connected = False mock_device.disconnect.side_effect = mock_disconnect # Create a mock testbed containing our mock device mock_testbed = Mock() mock_testbed.devices = {'my_mock_device': mock_device} mock_testbed.name = "mock_testbed" # --- 2. Define a simple health check YAML in-memory --- health_yaml_content = """ health_check_sections: section_version_check: commands: show version: - '.*Cisco IOS XE Software.*' # Checks for IOS XE in 'show version' output section_cpu_usage_check: commands: show processes cpu sorted: - 'CPU utilization for five seconds: [0-9]{1,2}%/' # Checks if CPU is valid percentage """ health_data = yaml.safe_load(health_yaml_content) # --- 3. Initialize and run Health checks --- try: # Use the mock device (in a real scenario, this would be from testbed.devices) my_device = mock_testbed.devices['my_mock_device'] my_device.connect() # This will call our mock_connect function # Create Health object with the device and parsed health data health = Health(device=my_device, health_data=health_data) # Run all defined health checks print(f"\nRunning health checks on {my_device.name}...") health_result = health.check_all() # Print results print("\nHealth Check Results Summary:") for section, result in health_result.items(): print(f" Section: '{section}' -> Status: {result['status']}") if result['status'] == 'Fail': print(f" Reason: {result.get('reason', 'No specific reason provided.')}") for command, cmd_result in result.get('commands', {}).items(): if cmd_result.get('status') == 'Fail': print(f" Command '{command}' failed: {cmd_result.get('reason', 'N/A')}") except Exception as e: print(f"An unexpected error occurred: {e}") finally: if my_device and my_device.connected: my_device.disconnect()
Debug
Known issues
breakingpyATS and Genie (including genie-libs-health) versions are tightly coupled. Installing incompatible versions can lead to `ImportError`, `AttributeError`, or unexpected behavior.
fix
Always install `pyats` and `genie-libs-health` (which pulls `genie`) from the same major release cycle. E.g., if `pyats` is 24.4, ensure `genie` is also from a compatible 24.x release. Check official pyATS documentation for version compatibility matrices.
affects: All versions, especially when upgrading.
gotchaHealth checks require a properly configured pyATS testbed and reachable network devices. Common failures stem from incorrect device IPs, usernames, passwords, or network connectivity issues.
fix
Before running health checks, ensure your `testbed.yaml` is accurate and that you can manually connect to the devices using the specified credentials and protocols. Use `pyats run job --testbed testbed.yaml` with a simple connection script to verify connectivity.
affects: All versions.
gotchaHealth check definitions in YAML must strictly adhere to the `genie-libs-health` schema. Syntax errors, incorrect command names, or malformed regex patterns will lead to runtime exceptions or incorrect check results.
fix
Carefully review your `health_check.yaml` file for correct YAML syntax (indentation, colons, list items) and ensure commands and patterns match device output expectations. Refer to the `genie-libs-health` documentation for the correct YAML schema.
affects: All versions.
gotchaUnderlying Genie operational parsers (`genie.libs.ops`) must successfully parse command output for health checks to function. If a parser fails, the health check for that command will report an error.
fix
If a health check fails unexpectedly, debug the underlying command execution and parsing. You can manually run `device.execute('show command')` and `device.parse('show command')` to isolate parsing issues before involving health checks.
affects: All versions.
Upgrade
Version history
26.5latest on PyPI · released May 28, 2026
Audit
Dependencies
pyatsrequiredCore test automation framework required to run testbeds and interact with devices.
genierequiredCore Genie library; genie-libs-health is a sub-library leveraging Genie's operational parsers and device abstractions.
Agent activity
4 hits · last 30 days
node
4
Resources
genie-libs-health — pip install genie-libs-health · libregistry