gasp

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# GASP - General AI Specialized Process Monitor

**GASP** is a Linux system monitoring tool designed specifically for AI consumption rather than human dashboards. It produces comprehensive, context-rich JSON output that enables AI agents (Claude, ChatGPT, etc.) to diagnose system issues, identify potential problems, and understand system state with minimal queries.

## Project Status

**Current Version:** 0.1.0-dev (MVP in progress)

> ⚠️ **SECURITY WARNING**: This version of GASP has **NO AUTHENTICATION**. It must run on trusted networks behind a firewall. **DO NOT EXPOSE THIS VERSION TO THE INTERNET.** Authentication will be added in an upcoming release.

**Implemented Features:**
- ✅ HTTP server with `/health`, `/metrics`, and `/version` endpoints
- ✅ CPU metrics collection (load averages, utilization, trend analysis)
- ✅ Memory metrics collection (usage, swap, pressure indicators)
- ✅ Rich contextual interpretations for all metrics
- ✅ Concurrent collector architecture
- ✅ Health scoring and concern detection
- ✅ **Claude Code skill bundled** - instant AI diagnostics for your infrastructure

**Planned Features:**
- 🔒 **Next up:** Authentication and authorization (API tokens, secure access)
- Disk I/O and usage metrics
- Network statistics and connection tracking
- Process information and top consumers
- Systemd unit monitoring
- Journal log analysis
- Desktop environment support (Hyprland, KDE, GNOME)
- GPU monitoring (NVIDIA/AMD)
- Baseline tracking and anomaly detection

See `AI-Monitor-Project-Specification.md` for the complete specification.

## Quick Start

### Build from Source

```bash
# Clone the repository
git clone https://github.com/accelerated-industries/gasp
cd gasp

# Build the binary
make build

# Run GASP
./gasp
```

The server will start on `http://localhost:8080` by default.

> 💡 **Tip:** After starting GASP, install the bundled Claude Code skill to enable instant AI diagnostics: `claude-code skill install ./skill/gasp-diagnostics.skill`

> ⚠️ **Remember:** This version has no authentication. Run only on trusted networks behind a firewall.

### Test the API

```bash
# Health check
curl http://localhost:8080/health | jq .

# Version information
curl http://localhost:8080/version | jq .

# Full system metrics
curl http://localhost:8080/metrics | jq .
```

## Example Output

```json
{
  "timestamp": "2025-12-15T17:43:46Z",
  "hostname": "hyperion",
  "uptime": "0m",
  "summary": {
    "health": "healthy",
    "concerns": [],
    "recent_changes": [],
    "score": 100
  },
  "cpu": {
    "load_avg_1m": 0.5,
    "load_avg_5m": 0.41,
    "load_avg_15m": 0.59,
    "cores": 64,
    "utilization_pct": 0.93,
    "baseline_load": 0.5,
    "interpretation": "normal load: load is 0.8% of capacity (0.50 on 64 cores), utilization 0.9%, near baseline",
    "trend": "stable"
  },
  "memory": {
    "total_mb": 257567,
    "used_mb": 12885,
    "available_mb": 244682,
    "usage_percent": 5.0,
    "swap_total_mb": 4095,
    "swap_used_mb": 0,
    "swap_percent": 0,
    "pressure_pct": 0,
    "oom_kills_recent": 0,
    "interpretation": "normal memory usage"
  }
}
```

## Key Design Principles

1. **AI-First Output:** Rich contextual information optimized for LLM consumption
2. **Interpretation Over Raw Data:** Every metric includes human-readable interpretation
3. **Single Source of Truth:** One comprehensive endpoint containing current state and trends
4. **Low Overhead:** Minimal system impact (<1% CPU, <50MB RAM)
5. **Easy Distribution:** Single static binary with no runtime dependencies

## API Endpoints

### GET /health
Returns service health status.

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2025-12-15T17:43:46Z",
  "service": "gasp"
}
```

### GET /version
Returns version and build information.

**Response:**
```json
{
  "service": "gasp",
  "version": "0.1.0-dev",
  "build": "development"
}
```

### GET /metrics
Returns comprehensive system snapshot with all collected metrics.

See example output above for structure.

## Development

### Build Commands

```bash
# Development build
make build

# Static binary (no CGO dependencies)
make build-static

# Build for multiple architectures
make build-all

# Run tests
make test

# Format code
make fmt

# Vet code
make vet

# Run locally
make run
```

### Project Structure

```
gasp/
├── cmd/
│   └── gasp/           # Main entry point
├── internal/
│   ├── collectors/     # Metric collectors
│   │   ├── collector.go
│   │   ├── cpu.go
│   │   └── memory.go
│   ├── types/          # Data structures
│   │   └── metrics.go
│   ├── server/         # HTTP server
│   │   └── http.go
│   ├── baseline/       # Baseline tracking (TODO)
│   └── config/         # Configuration (TODO)
├── configs/            # Config files and systemd service
└── scripts/            # Installation scripts
```

### Adding New Collectors

1. Implement the `Collector` interface in `internal/collectors/`
2. Add collection logic reading from `/proc` or `/sys`
3. Include interpretation and trend analysis
4. Register the collector in `cmd/gasp/main.go`

See `internal/collectors/cpu.go` or `memory.go` for examples.

## Configuration

Currently GASP uses command-line flags:

```bash
./gasp --port 8080              # Set HTTP port (default: 8080)
./gasp --config /path/to/config # Load config file (not yet implemented)
./gasp --version                # Show version and exit
```

Configuration file support is planned for Phase 2.

## Architecture

GASP uses a **collector-based architecture** with concurrent metric gathering:

1. Multiple specialized collectors (CPU, Memory, Disk, etc.)
2. Each collector implements a common interface
3. Collectors run concurrently using goroutines
4. Results aggregated into a SystemSnapshot
5. Served via HTTP JSON API

Different metrics are collected at different rates:
- **High-frequency (10s):** CPU, memory, load
- **Medium-frequency (30s):** Processes, network, disk I/O (planned)
- **Low-frequency (5m):** Logs, systemd units (planned)

## Performance Targets

- Binary size: < 15MB
- Memory footprint: < 50MB
- CPU overhead: < 1% (idle), < 5% (during collection)
- HTTP response time: < 100ms
- Collection cycle: < 2 seconds

## Target Platforms

**Primary Support (Phase 1):**
- Arch Linux (workstations)
- Debian/Ubuntu (servers)

**Future Support:**
- Proxmox VE
- Docker/container hosts
- Raspberry Pi / ARM devices

## AI Integration

### Claude Code Skill (Included!)

GASP includes a **ready-to-use Claude Code skill** that enables instant, intelligent system diagnostics. Once GASP is running on your systems, Claude Code can automatically fetch metrics and provide expert-level analysis of your infrastructure.

#### Installing the Skill

```bash
# From the GASP repository root
claude-code skill install ./skill/gasp-diagnostics.skill
```

Once installed, Claude Code can diagnose any GASP-enabled host on your network:

**Natural language diagnostics:**
- "Check hyperion for me"
- "What's wrong with accelerated.local?"
- "Compare my proxmox nodes"
- "Is the dev server having memory issues?"
- "Why is 192.168.1.100 slow?"

#### What the Skill Does

The `gasp-diagnostics` skill empowers Claude Code to:

1. **Automatically fetch** metrics from any GASP-enabled host via HTTP
2. **Intelligently analyze** system state using metric correlation and baselines
3. **Identify issues** with context-aware pattern recognition (dev workstation vs server vs VM host)
4. **Provide actionable recommendations** specific to the detected problem
5. **Compare multiple hosts** to identify outliers and correlated issues
6. **Understand system context** (desktop environments, container hosts, GPU workloads, etc.)

**Example interaction:**
```
You: Check accelerated.local
Claude: Fetching metrics from accelerated.local...

Issue detected: Memory pressure at 8.2%. The postgres container started
swapping 2 hours ago and is now using 12GB RAM (up from 4GB baseline).
This likely indicates a query leak.

Recommendation: Check recent queries and consider restarting the container.
```

The skill handles network topology automatically - works with mDNS (.local), DNS names, and IP addresses on your trusted network.

#### Security Note for the Skill

The skill connects to GASP instances on port 8080 by default. Since this version has no authentication, ensure:
- GASP runs only on trusted internal networks
- Firewall rules prevent external access to port 8080
- You trust all hosts on the network where GASP is deployed

### Direct API Usage

For non-Claude AI agents or custom integrations:

```bash
# Fetch metrics via curl
curl -s http://hyperion:8080/metrics | jq .

# Multi-host collection script
for host in hyperion proxmox1 proxmox2; do
  curl -s http://${host}:8080/metrics > /tmp/${host}.json
done
```

### Future: MCP Server
A Model Context Protocol (MCP) server is planned to provide even deeper integration with AI tools beyond Claude Code.

## Project Roadmap

GASP is under active development. Here's what's planned:

### Phase 1: Security & Authentication (Next Priority)
- **API token authentication** - Secure access control with token generation and validation
- **Token management** - Utilities for creating, revoking, and rotating tokens
- **Skill updates** - Update the bundled Claude Code skill to support authenticated requests
- **TLS/HTTPS support** - Encrypted transport for production deployments
- **Role-based access** - Read-only vs admin tokens for different use cases

### Phase 2: Enhanced Metrics Collection
- **Disk I/O monitoring** - IOPS, throughput, latency per device
- **Network statistics** - Interface traffic, connections, bandwidth utilization
- **Process information** - Top consumers, detailed process trees, resource tracking
- **Systemd integration** - Unit states, failed services, restart tracking
- **Journal log analysis** - Error rate trending, pattern detection, log correlation

### Phase 3: Advanced Analysis
- **Baseline learning** - 24-hour rolling baselines for anomaly detection
- **Trend analysis** - Statistical deviation detection (2-sigma alerts)
- **Predictive alerts** - Warning before resources are exhausted
- **Persistent baselines** - Store learned behavior across restarts
- **Seasonal patterns** - Weekday vs weekend, business hours vs off-hours

### Phase 4: Desktop & GPU Support
- **Desktop environment detection** - Hyprland, KDE, GNOME, Xorg, Wayland
- **Active window tracking** - Context-aware resource attribution
- **GPU monitoring** - NVIDIA (nvidia-smi), AMD (rocm-smi), Intel
- **Per-process GPU usage** - GPU memory and utilization attribution
- **Thermal monitoring** - Temperature tracking and throttling detection

### Phase 5: Distribution & Deployment
- **Packaging** - AUR (Arch), .deb (Debian/Ubuntu), .rpm (RHEL/Fedora)
- **Systemd hardening** - Enhanced security directives and isolation
- **Auto-installation** - One-command deployment scripts
- **Docker image** - Containerized GASP for Docker hosts
- **Configuration management** - YAML config file support, environment variable overrides

### Phase 6: AI Tooling Ecosystem
- **MCP server implementation** - Native Model Context Protocol support
- **Multi-agent coordination** - Skills for fleet-wide diagnostics
- **Historical data API** - Time-series metrics for trend analysis
- **Alert webhooks** - Proactive notifications for critical issues
- **Integration guides** - Documentation for other AI frameworks (LangChain, AutoGPT, etc.)

### Future Considerations
- Web UI for human consumption (low priority - AI-first focus maintained)
- Plugin system for custom collectors
- Remote host monitoring (agent-based deployment)
- Kubernetes/container orchestration integration
- Windows support (significant undertaking)

> **Note:** This roadmap is subject to change based on user feedback and emerging requirements. The priority is to maintain GASP's core philosophy: AI-first monitoring with rich contextual output.

## License

GASP is licensed under the [GNU General Public License v3.0](https://github.com/AcceleratedIndustries/gasp/tree/HEAD/LICENSE). This ensures that GASP and any derivatives remain free and open source software.

## Contributing

This is the first Go project at Accelerated Industries. Contributions, suggestions, and feedback are welcome!

See `CLAUDE.md` for detailed development guidance.

## Acknowledgments

- Inspired by Prometheus Node Exporter, Netdata, and Telegraf
- Built for the AI-first monitoring paradigm
- Part of the Accelerated Industries warehouse control system ecosystem

GASP - General AI Specialized Process Monitor

GASP is a Linux system monitoring tool designed specifically for AI consumption rather than human dashboards. It produces comprehensive, context-rich JSON output that enables AI agents (Claude, ChatGPT, etc.) to diagnose system issues, identify potential problems, and understand system state with minimal queries.

Project Status

Current Version: 0.1.0-dev (MVP in progress)

⚠️ SECURITY WARNING: This version of GASP has NO AUTHENTICATION. It must run on trusted networks behind a firewall. DO NOT EXPOSE THIS VERSION TO THE INTERNET. Authentication will be added in an upcoming release.

Implemented Features:

✅ HTTP server with /health, /metrics, and /version endpoints
✅ CPU metrics collection (load averages, utilization, trend analysis)
✅ Memory metrics collection (usage, swap, pressure indicators)
✅ Rich contextual interpretations for all metrics
✅ Concurrent collector architecture
✅ Health scoring and concern detection
✅ Claude Code skill bundled - instant AI diagnostics for your infrastructure

Planned Features:

🔒 Next up: Authentication and authorization (API tokens, secure access)
Disk I/O and usage metrics
Network statistics and connection tracking
Process information and top consumers
Systemd unit monitoring
Journal log analysis
Desktop environment support (Hyprland, KDE, GNOME)
GPU monitoring (NVIDIA/AMD)
Baseline tracking and anomaly detection

See AI-Monitor-Project-Specification.md for the complete specification.

Quick Start

Build from Source

# Clone the repository
git clone https://github.com/accelerated-industries/gasp
cd gasp

# Build the binary
make build

# Run GASP
./gasp

The server will start on http://localhost:8080 by default.

💡 Tip: After starting GASP, install the bundled Claude Code skill to enable instant AI diagnostics: claude-code skill install ./skill/gasp-diagnostics.skill

⚠️ Remember: This version has no authentication. Run only on trusted networks behind a firewall.

Test the API

# Health check
curl http://localhost:8080/health | jq .

# Version information
curl http://localhost:8080/version | jq .

# Full system metrics
curl http://localhost:8080/metrics | jq .

Example Output

{
  "timestamp": "2025-12-15T17:43:46Z",
  "hostname": "hyperion",
  "uptime": "0m",
  "summary": {
    "health": "healthy",
    "concerns": [],
    "recent_changes": [],
    "score": 100
  },
  "cpu": {
    "load_avg_1m": 0.5,
    "load_avg_5m": 0.41,
    "load_avg_15m": 0.59,
    "cores": 64,
    "utilization_pct": 0.93,
    "baseline_load": 0.5,
    "interpretation": "normal load: load is 0.8% of capacity (0.50 on 64 cores), utilization 0.9%, near baseline",
    "trend": "stable"
  },
  "memory": {
    "total_mb": 257567,
    "used_mb": 12885,
    "available_mb": 244682,
    "usage_percent": 5.0,
    "swap_total_mb": 4095,
    "swap_used_mb": 0,
    "swap_percent": 0,
    "pressure_pct": 0,
    "oom_kills_recent": 0,
    "interpretation": "normal memory usage"
  }
}

Key Design Principles

AI-First Output: Rich contextual information optimized for LLM consumption
Interpretation Over Raw Data: Every metric includes human-readable interpretation
Single Source of Truth: One comprehensive endpoint containing current state and trends
Low Overhead: Minimal system impact (<1% CPU, <50MB RAM)
Easy Distribution: Single static binary with no runtime dependencies

API Endpoints

GET /health

Returns service health status.

Response:

{
  "status": "healthy",
  "timestamp": "2025-12-15T17:43:46Z",
  "service": "gasp"
}

GET /version

Returns version and build information.

Response:

{
  "service": "gasp",
  "version": "0.1.0-dev",
  "build": "development"
}

GET /metrics

Returns comprehensive system snapshot with all collected metrics.

See example output above for structure.

Development

Build Commands

# Development build
make build

# Static binary (no CGO dependencies)
make build-static

# Build for multiple architectures
make build-all

# Run tests
make test

# Format code
make fmt

# Vet code
make vet

# Run locally
make run

Project Structure

gasp/
├── cmd/
│   └── gasp/           # Main entry point
├── internal/
│   ├── collectors/     # Metric collectors
│   │   ├── collector.go
│   │   ├── cpu.go
│   │   └── memory.go
│   ├── types/          # Data structures
│   │   └── metrics.go
│   ├── server/         # HTTP server
│   │   └── http.go
│   ├── baseline/       # Baseline tracking (TODO)
│   └── config/         # Configuration (TODO)
├── configs/            # Config files and systemd service
└── scripts/            # Installation scripts

Adding New Collectors

Implement the Collector interface in internal/collectors/
Add collection logic reading from /proc or /sys
Include interpretation and trend analysis
Register the collector in cmd/gasp/main.go

See internal/collectors/cpu.go or memory.go for examples.

Configuration

Currently GASP uses command-line flags:

./gasp --port 8080              # Set HTTP port (default: 8080)
./gasp --config /path/to/config # Load config file (not yet implemented)
./gasp --version                # Show version and exit

Configuration file support is planned for Phase 2.

Architecture

GASP uses a collector-based architecture with concurrent metric gathering:

Multiple specialized collectors (CPU, Memory, Disk, etc.)
Each collector implements a common interface
Collectors run concurrently using goroutines
Results aggregated into a SystemSnapshot
Served via HTTP JSON API

Different metrics are collected at different rates:

High-frequency (10s): CPU, memory, load
Medium-frequency (30s): Processes, network, disk I/O (planned)
Low-frequency (5m): Logs, systemd units (planned)

Performance Targets

Binary size: < 15MB
Memory footprint: < 50MB
CPU overhead: < 1% (idle), < 5% (during collection)
HTTP response time: < 100ms
Collection cycle: < 2 seconds

Target Platforms

Primary Support (Phase 1):

Arch Linux (workstations)
Debian/Ubuntu (servers)

Future Support:

Proxmox VE
Docker/container hosts
Raspberry Pi / ARM devices

AI Integration

Claude Code Skill (Included!)

GASP includes a ready-to-use Claude Code skill that enables instant, intelligent system diagnostics. Once GASP is running on your systems, Claude Code can automatically fetch metrics and provide expert-level analysis of your infrastructure.

Installing the Skill

# From the GASP repository root
claude-code skill install ./skill/gasp-diagnostics.skill

Once installed, Claude Code can diagnose any GASP-enabled host on your network:

Natural language diagnostics:

"Check hyperion for me"
"What's wrong with accelerated.local?"
"Compare my proxmox nodes"
"Is the dev server having memory issues?"
"Why is 192.168.1.100 slow?"

What the Skill Does

The gasp-diagnostics skill empowers Claude Code to:

Automatically fetch metrics from any GASP-enabled host via HTTP
Intelligently analyze system state using metric correlation and baselines
Identify issues with context-aware pattern recognition (dev workstation vs server vs VM host)
Provide actionable recommendations specific to the detected problem
Compare multiple hosts to identify outliers and correlated issues
Understand system context (desktop environments, container hosts, GPU workloads, etc.)

Example interaction:

You: Check accelerated.local
Claude: Fetching metrics from accelerated.local...

Issue detected: Memory pressure at 8.2%. The postgres container started
swapping 2 hours ago and is now using 12GB RAM (up from 4GB baseline).
This likely indicates a query leak.

Recommendation: Check recent queries and consider restarting the container.

The skill handles network topology automatically - works with mDNS (.local), DNS names, and IP addresses on your trusted network.

Security Note for the Skill

The skill connects to GASP instances on port 8080 by default. Since this version has no authentication, ensure:

GASP runs only on trusted internal networks
Firewall rules prevent external access to port 8080
You trust all hosts on the network where GASP is deployed

Direct API Usage

For non-Claude AI agents or custom integrations:

# Fetch metrics via curl
curl -s http://hyperion:8080/metrics | jq .

# Multi-host collection script
for host in hyperion proxmox1 proxmox2; do
  curl -s http://${host}:8080/metrics > /tmp/${host}.json
done

Future: MCP Server

A Model Context Protocol (MCP) server is planned to provide even deeper integration with AI tools beyond Claude Code.

Project Roadmap

GASP is under active development. Here's what's planned:

Phase 1: Security & Authentication (Next Priority)

API token authentication - Secure access control with token generation and validation
Token management - Utilities for creating, revoking, and rotating tokens
Skill updates - Update the bundled Claude Code skill to support authenticated requests
TLS/HTTPS support - Encrypted transport for production deployments
Role-based access - Read-only vs admin tokens for different use cases

Phase 2: Enhanced Metrics Collection

Disk I/O monitoring - IOPS, throughput, latency per device
Network statistics - Interface traffic, connections, bandwidth utilization
Process information - Top consumers, detailed process trees, resource tracking
Systemd integration - Unit states, failed services, restart tracking
Journal log analysis - Error rate trending, pattern detection, log correlation

Phase 3: Advanced Analysis

Baseline learning - 24-hour rolling baselines for anomaly detection
Trend analysis - Statistical deviation detection (2-sigma alerts)
Predictive alerts - Warning before resources are exhausted
Persistent baselines - Store learned behavior across restarts
Seasonal patterns - Weekday vs weekend, business hours vs off-hours

Phase 4: Desktop & GPU Support

Desktop environment detection - Hyprland, KDE, GNOME, Xorg, Wayland
Active window tracking - Context-aware resource attribution
GPU monitoring - NVIDIA (nvidia-smi), AMD (rocm-smi), Intel
Per-process GPU usage - GPU memory and utilization attribution
Thermal monitoring - Temperature tracking and throttling detection

Phase 5: Distribution & Deployment

Packaging - AUR (Arch), .deb (Debian/Ubuntu), .rpm (RHEL/Fedora)
Systemd hardening - Enhanced security directives and isolation
Auto-installation - One-command deployment scripts
Docker image - Containerized GASP for Docker hosts
Configuration management - YAML config file support, environment variable overrides

Phase 6: AI Tooling Ecosystem

MCP server implementation - Native Model Context Protocol support
Multi-agent coordination - Skills for fleet-wide diagnostics
Historical data API - Time-series metrics for trend analysis
Alert webhooks - Proactive notifications for critical issues
Integration guides - Documentation for other AI frameworks (LangChain, AutoGPT, etc.)

Future Considerations

Web UI for human consumption (low priority - AI-first focus maintained)
Plugin system for custom collectors
Remote host monitoring (agent-based deployment)
Kubernetes/container orchestration integration
Windows support (significant undertaking)

Note: This roadmap is subject to change based on user feedback and emerging requirements. The priority is to maintain GASP's core philosophy: AI-first monitoring with rich contextual output.

License

GASP is licensed under the GNU General Public License v3.0. This ensures that GASP and any derivatives remain free and open source software.

Contributing

This is the first Go project at Accelerated Industries. Contributions, suggestions, and feedback are welcome!

See CLAUDE.md for detailed development guidance.

Acknowledgments

Inspired by Prometheus Node Exporter, Netdata, and Telegraf
Built for the AI-first monitoring paradigm
Part of the Accelerated Industries warehouse control system ecosystem