syinfo 0.3.0

A comprehensive Python package for hardware, network, and software information gathering with advanced monitoring capabilities

SyInfo - Simple System Information Library

A simple, well-designed Python library for gathering system information including hardware specifications, network configuration, real-time system monitoring, and analysis utilities (log search, package inventory).

Key Features

Device Information

• CPU Details: Model, cores, frequency, usage statistics
• Memory Analysis: RAM, swap, detailed memory mapping
• Storage Info: Disk usage, I/O statistics, filesystem details
• GPU Detection: NVIDIA, AMD, Intel graphics cards
• Device Identification: Manufacturer, model, serial numbers

Network Capabilities

• Interface Detection: All network adapters with detailed info
• Connectivity Analysis: Public/private IP, DNS, gateways
• Device Discovery: Scan and identify devices on local network
• Network I/O Statistics: Real-time and historical data
• WiFi Information: SSID, signal strength, encryption

System Monitoring (New!)

• Real-time Monitoring: CPU, memory, disk, and network tracking
• Customizable Intervals: 1 second to hours, configurable duration
• JSON Export: Perfect for scripting and automation with jq
• Performance Analytics: Averages, peaks, and trend analysis
• Non-blocking: Background monitoring with graceful interruption

Powerful CLI Interface + Analysis

• Flag-based Commands: Easy scripting (syinfo --system-monitor --json -t 10 | jq '.summary')
• JSON Output: Native jq compatibility for data processing
• Monitoring Support: Real-time system performance tracking
• Flexible Options: Combine flags for exactly what you need
• Log Analysis: -l/--logs with filters (--pattern, --level, --limit)
• Package Inventory: -p/--packages with --manager and --name filters

Advanced Logging (New!)

• Production-Ready: Sophisticated singleton logger with advanced features
• Incident Tracking: Automatic numbering of warnings and errors
• Enhanced Tracebacks: Beautiful, readable error traces with file context
• Multiple Outputs: Console, files, and system log (syslog) simultaneously
• Runtime Configuration: Dynamic log levels, handler management, statistics
• Platform-Aware: Auto-detects syslog paths for Linux, macOS, and Windows

Installation

pip install syinfo

From source (local)

# Clone and install in editable mode (recommended for development)
git clone https://github.com/MR901/syinfo.git
cd syinfo
python -m venv .venv && source .venv/bin/activate  # optional but recommended
pip install -e .

# Alternatively, install directly from a local path
pip install /path/to/syinfo  # installs from sdist/wheel if present
pip install -e /path/to/syinfo  # editable install from local directory

# Build wheel/sdist locally (optional)
python -m build
pip install dist/syinfo-*.whl

Quick Start

Basic Usage

from syinfo import DeviceInfo, SystemInfo

# Get comprehensive system information
info = SystemInfo.get_all(search_period=0, search_device_vendor_too=False)
print(f"Hostname: {info.get('dev_info', {}).get('static_hostname')}")
print(f"CPU cores: {info.get('cpu_info', {}).get('cores', {}).get('total')}")

Hardware Information

# Get detailed hardware info
from syinfo import DeviceInfo
hardware = DeviceInfo.get_all()

print("CPU Information:")
print(f"  Model: {hardware['cpu']['model']}")
print(f"  Cores: {hardware['cpu']['cores_physical']} physical")
print(f"  Usage: {hardware['cpu']['usage_percent']:.1f}%")

print("Memory Information:")  
print(f"  Total: {hardware['memory']['total']}")
print(f"  Available: {hardware['memory']['available']}")
print(f"  Usage: {hardware['memory']['usage_percent']:.1f}%")

Network Discovery

# Discover devices on network (sudo recommended)
from syinfo.core.search_network import search_devices_on_network
devices = search_devices_on_network(time=10)
for ip, dev in (devices or {}).items():
    print(f"  {ip:15} - {dev.get('mac_address')} ({dev.get('vendor')})")

System Monitoring

# Create a system monitor
from syinfo import SystemMonitor
monitor = SystemMonitor(interval=5)

# Start monitoring for 60 seconds
monitor.start(duration=60)
import time
time.sleep(61)
results = monitor.stop()

print(f"Average CPU Usage: {results['summary']['cpu_avg']:.1f}%")
print(f"Peak Memory Usage: {results['summary']['memory_peak']:.1f}%")
print(f"Data Points Collected: {results['total_points']}")

CLI Interface - Flag-Based Commands

Device Information

# Device/hardware information
syinfo -d

# With JSON output
syinfo -d --json | jq '.cpu_info.cores'

Network Operations

# Network information
syinfo -n -t 10          # Network summary (no scan without sudo)

# Network with device info
syinfo -s                # Combined system info

# JSON output for parsing
syinfo -n --json | jq '.'

System Monitoring

# Monitor system for 30 seconds, 5-second intervals
syinfo --system-monitor -t 30 -i 5

# JSON monitoring data
syinfo --system-monitor --json -t 60 -i 10 | tail -1 | jq '.summary'

# Extract specific metrics
syinfo -mpj -t 120 -i 15 | tail -1 | jq -r '.summary.cpu_avg'

# Visualize monitoring JSONL (Python)
from syinfo.resource_monitor.visualization import create_monitoring_plot
create_monitoring_plot("./monitoring/monitor-YYYYMMDD-HHMMSS.jsonl")

Advanced CLI Usage

# Disable formatted output, just get JSON
syinfo -d --json > device_info.json

# Network scan (sudo) without vendor lookup (faster)
sudo syinfo -N --disable-vendor-search --json | jq 'keys | length'

# Monitor and process with jq
syinfo --system-monitor --json -t 60 -i 10 | tail -1 | jq '.data_points[].cpu_percent | max'

# Complex monitoring workflows
CPU_AVG=$(syinfo --system-monitor --json -t 30 -i 5 | tail -1 | jq -r '.summary.cpu_avg')
if (( $(echo "$CPU_AVG > 80" | bc -l) )); then
  echo "High CPU usage detected: $CPU_AVG%"
fi

CLI Flag Reference

Flag	Long Flag	Description
-d	--device	Show device/hardware information
-n	--network	Show network information and scan devices
-s	--system	Show combined device and network information
	--system-monitor	Start system monitoring
	--process-monitor	Start process-specific monitoring
-l	--logs	Query system logs (use --pattern/--level/--limit)
-p	--packages	List installed packages (use --manager/--name)
-t	--time	Duration in seconds (network scan or monitoring)
-i	--interval	Monitoring interval in seconds (default: 5)
-p	--disable-print	Suppress formatted output
-j	--return-json	Output as JSON
-o	--disable-vendor-search	Skip vendor lookup (faster network scans)

System Monitoring Features

Real-time Performance Tracking

• CPU Usage: Per-core and overall utilization
• Memory Statistics: Usage, available, swap information
• Disk I/O: Read/write operations and usage percentages
• Network Activity: Bytes and packets sent/received

JSON Data Structure

{
  "total_points": 12,
  "data_points": [
    {
      "timestamp": "2025-09-14T02:20:42.029017",
      "cpu_percent": 7.8,
      "memory_percent": 68.2,
      "disk_percent": 82.8,
      "network_io": {
        "bytes_sent": 3301001170,
        "bytes_recv": 4409283972,
        "packets_sent": 3556700,
        "packets_recv": 5418377
      }
    }
  ],
  "summary": {
    "duration_seconds": 60,
    "cpu_avg": 5.3,
    "cpu_max": 8.3,
    "memory_avg": 68.2,
    "memory_peak": 68.4,
    "disk_avg": 82.8,
    "start_time": "2025-09-14T02:20:42.029017",
    "end_time": "2025-09-14T02:21:42.029017"
  }
}

Monitoring Use Cases

# Server performance monitoring
syinfo -mpj -t 3600 -i 60 | tail -1 > hourly_stats.json

# Quick system check
syinfo -m -t 10 -i 2

# CPU spike detection
syinfo -mpj -t 300 -i 5 | tail -1 | jq '.data_points[] | select(.cpu_percent > 90)'

# Network throughput analysis
syinfo -mpj -t 120 -i 10 | tail -1 | jq '.data_points | [.[0], .[-1]] | .[1].network_io.bytes_sent - .[0].network_io.bytes_sent'

Advanced Logging

SyInfo includes a production-ready logging system:

from syinfo import Logger, LoggerConfig
import logging

# Basic usage
logger = syinfo.Logger.get_logger()
logger.info("Application started")

# Advanced configuration
config = LoggerConfig(
    log_level=logging.DEBUG,
    log_files=["app.log", "debug.log"],
    output_to_stdout=True,
    verbose_logs=True,           # Include function names and line numbers
    enable_incident_counting=True, # Number warnings/errors
    enable_traceback=True,       # Beautiful formatted tracebacks
    enable_syslog=True           # System log integration
)

logger = Logger.get_logger(config)
logger.warning("This will be numbered")  # (incident #1) This will be numbered

# Runtime management
logger_instance = syinfo.Logger.get_instance()
stats = logger_instance.get_stats()
print(f"Warnings: {stats['warning_count']}, Errors: {stats['error_count']}")

Error Handling

from syinfo.exceptions import SystemAccessError, DataCollectionError

logger = syinfo.Logger.get_logger()

try:
    info = syinfo.get_system_info()
    logger.info("System info collected successfully")
except SystemAccessError as e:
    logger.error(f"Permission error: {e}")  # Includes traceback if enabled
except DataCollectionError as e:
    logger.error(f"Data collection failed: {e}")

Performance & Reliability

Benchmarks

• Data Collection: < 2 seconds for complete system scan
• Memory Usage: < 50MB peak memory consumption
• Network Scan: < 15 seconds for typical home network
• Monitoring Overhead: < 1% CPU during continuous monitoring

Development

Setup

git clone https://github.com/MR901/syinfo.git
cd syinfo
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -e .[dev]

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=syinfo --cov-report=html

# Test monitoring functionality
python -c "from syinfo import SystemMonitor; m=SystemMonitor(1); m.start(5); import time; time.sleep(6); print(m.stop())"

Examples

Check out the organized examples/ directory:

• Basic: examples/basic/ (device, system, network, export)
• Analysis: examples/analysis/ (logs, packages, system health/search)
• Monitoring: examples/monitoring/ (simple monitoring)
• CLI: examples/cli/USAGE.md

Run everything:

python -m examples.run_all

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Email: [e-mail]
• GitHub: https://github.com/MR901/syinfo