sysmetrics

SysMetrics

A powerful, interactive terminal-based system monitoring tool built in Go that provides real-time system metrics visualization and flexible logging capabilities.

Features

Real-time System Monitoring

• CPU Usage: Per-core and overall CPU utilization with visual progress bars
• Memory Information: RAM usage, available memory, and detailed statistics
• Disk Usage: Storage utilization across all mounted drives
• Network Statistics: Network interface statistics and throughput
• Host Information: System details including OS, platform, and uptime

Interactive Terminal UI

• Bubble Tea Framework: Smooth, responsive terminal user interface
• Multiple View Modes: Switch between monitoring, streaming, and management modes
• Keyboard Navigation: Intuitive controls with arrow keys and shortcuts
• Real-time Updates: Configurable refresh intervals (default 2 seconds)
• Search Functionality: Filter and search through metrics

Data Streaming & Logging

• Multiple Output Formats: Support for 11+ industry-standard log formats
  • OpenTelemetry (JSON)
  • OTLP Text Line Protocol
  • Prometheus
  • JSON Lines
  • InfluxDB Line Protocol
  • AWS CloudWatch
  • CSV/TSV
  • XML/YAML
  • Syslog (RFC 5424)
• Flexible Intervals: Stream data per minute, hourly, or daily
• Background Processing: Run multiple streaming processes simultaneously

Background Process Management

• Independent Processes: Spawn and manage background streaming processes
• Process Lifecycle: Start, stop, list, and delete background processes
• Real-time Status: Monitor process health and statistics
• Graceful Shutdown: Clean termination with summary logging
• Concurrent Operations: Multiple processes can run simultaneously

Log Management

• Automatic Directory Creation: Creates log directories as needed
• Format-specific Files: Appropriate file extensions for each format
• Process Summaries: Detailed logs of process lifecycle events
• Configurable Paths: Custom log directory locations

Quick Start

Installation

SysMetrics can be installed in multiple ways. Choose the method that best suits your needs:

Option 1: One-Line Install (Easiest)

Install the latest version with a single command:

curl -fsSL https://raw.githubusercontent.com/razpinator/sysmetrics/master/install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/razpinator/sysmetrics/master/install.sh | bash

This script automatically detects your platform and installs the appropriate binary to /usr/local/bin.

Option 2: Go Install (Recommended for Go Users)

If you have Go installed, you can install SysMetrics directly:

go install github.com/razpinator/sysmetrics@latest

This installs the latest version to your $GOPATH/bin directory. Make sure this directory is in your PATH.

Option 3: Download Pre-built Binaries

Download the latest release for your platform from the GitHub Releases page:

• macOS (Intel): sysmetrics-darwin-amd64
• macOS (Apple Silicon): sysmetrics-darwin-arm64
• Linux (x86_64): sysmetrics-linux-amd64
• Windows (x64): sysmetrics-windows-amd64.exe

After downloading, make the binary executable and move it to your PATH:

# macOS/Linux
chmod +x sysmetrics-*
sudo mv sysmetrics-* /usr/local/bin/sysmetrics

# Windows
# Move the .exe file to a directory in your PATH

Option 4: Build from Source

Prerequisites

• Go 1.25.1 or later
• Git
• Make (optional, for easier building)

Quick Build

git clone https://github.com/razpinator/sysmetrics.git
cd sysmetrics
go build -o sysmetrics .
./sysmetrics

Using Make (Recommended for Development)

git clone https://github.com/razpinator/sysmetrics.git
cd sysmetrics

# Build the binary
make build

# Install to /usr/local/bin (requires sudo)
make install

# Or just run directly
make run

Available Make Targets

• make build - Build the binary
• make install - Install to system PATH
• make uninstall - Remove from system PATH
• make test - Run tests
• make clean - Clean build artifacts
• make cross-compile - Build for multiple platforms
• make help - Show all available targets

Option 5: Package Managers

Homebrew (macOS)

# Coming soon
brew install razpinator/tap/sysmetrics

Arch Linux (AUR)

# Coming soon
yay -S sysmetrics

Verification

After installation, verify SysMetrics is working:

sysmetrics --version
sysmetrics --help

CLI Usage

Basic Commands

# Run SysMetrics (interactive mode)
sysmetrics

# Show version information
sysmetrics --version
sysmetrics -v

# Show help information
sysmetrics --help
sysmetrics -h

Interactive Mode

Once you run sysmetrics, you'll enter the interactive terminal interface:

1. Launch the application and you'll see the main menu
2. Navigate using arrow keys (↑/↓)
3. Select a metric type to monitor (CPU, Memory, Disk, Network, Host, or All)
4. Press Enter to start real-time monitoring
5. Press 'q' to return to the main menu or exit

Command Line Options

Quick Start

Simply run the following command to start monitoring your system:

sysmetrics

The application will open in interactive mode with an intuitive menu system.

📖 Detailed Usage

Main Menu Options

• 📊 All Metrics: Monitor all system metrics simultaneously
• 🔥 CPU Usage: Detailed CPU monitoring with per-core breakdown
• 💾 Memory Info: RAM usage and memory statistics
• 💿 Disk Usage: Storage utilization across drives
• 🌐 Network Stats: Network interface statistics
• ℹ️ Host Info: System information and details
• 📝 Stream to Logs: Configure and start log streaming
• 🔧 Manage Background Processes: Control background streaming processes

Keyboard Controls

Main Menu

• ↑/↓: Navigate menu options
• Enter: Select option
• / or s: Search metrics
• q: Quit application

Monitoring Mode

• b: Back to main menu
• ↑/↓: Change update interval
• q: Quit to main menu

Background Process Management

• n: Start new background process
• s: Stop selected process
• d: Delete stopped process
• a: Stop all processes
• ↑/↓: Navigate process list
• b: Back to previous menu

Stream Configuration

• ↑/↓: Navigate options
• Enter: Confirm selection
• b: Back to previous menu

Setting Up Log Streaming

1. From main menu, select "📝 Stream to Logs"
2. Choose format from the available options
3. Select interval (Per Minute, Hourly, Daily)
4. Streaming starts automatically with visual feedback
5. Log files are created in ./logs/ directory

Managing Background Processes

1. Select "🔧 Manage Background Processes" from main menu
2. Press 'n' to create a new background process
3. Configure format and interval for the new process
4. Monitor process status in real-time
5. Use 's' to stop or 'd' to delete' stopped processes

Project Structure

sysmetrics/
├── main.go                 # Application entry point
├── go.mod                  # Go module dependencies
├── internal/               # Internal packages
│   ├── logging/           # Background streaming and log formatting
│   ├── metrics/           # System metrics collection
│   ├── model/             # Bubble Tea application model
│   ├── types/             # Type definitions and constants
│   ├── ui/                # UI styles and views
│   └── utils/             # Utility functions
└── logs/                   # Generated log files (created at runtime)

Configuration

Environment Variables

The application uses sensible defaults but can be configured through the UI:

• Update Interval: Configurable from 1-10 seconds
• Log Directory: Default ./logs/ (automatically created)
• Stream Intervals: Per minute, hourly, or daily
• Log Formats: 11 supported formats

Supported Log Formats

Dependencies

Core Dependencies

• Bubble Tea: Terminal UI framework
• Bubbles: UI components for Bubble Tea
• Lipgloss: Style definitions for terminal UIs
• gopsutil: Cross-platform system metrics library
• yaml.v3: YAML processing library

Automatic Dependencies

All transitive dependencies are automatically managed by Go modules.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is open source. Please check the license file for details.

Troubleshooting

Common Issues

Application won't start:

• Ensure Go 1.25.1+ is installed
• Run go mod download to install dependencies
• Check terminal compatibility (colors and alternate screen)

Metrics not updating:

• Verify system permissions for reading system metrics
• Check if gopsutil is compatible with your OS
• Try running with elevated privileges if needed

Background processes not working:

• Ensure write permissions to the log directory
• Check available disk space
• Verify no conflicting processes are using the same files

Log files not created:

• Check write permissions in the current directory
• Ensure sufficient disk space
• Verify the log path is accessible

Getting Help

1. Check existing issues in the repository
2. Review the documentation
3. Create a detailed issue with system information and error messages

Version History

See the commit history for detailed changes and improvements.

SysMetrics - Making system monitoring intuitive and powerful! 🚀