From 2000fb5d53fd655e63f9ffdc12ada16faa031483 Mon Sep 17 00:00:00 2001 From: alex Date: Fri, 7 Nov 2025 19:14:52 +0100 Subject: [PATCH] feat: initial symon implementation - lightweight OTEL metrics exporter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Symon is a dedicated system metrics exporter for OpenTelemetry, purpose-built for headless operation in server environments. Core Features: - Lightweight daemon with minimal resource footprint - Comprehensive system metrics (CPU, memory, network, disk, processes, temp) - Smart process filtering with regex pattern support - External config file inclusion for server-specific process lists - Native OTLP export via gRPC Components: - src/main.rs: Daemon loop with graceful shutdown - src/config.rs: Configuration with process filtering and includes - src/collector.rs: System metrics collection using sysinfo - src/exporter.rs: OpenTelemetry OTLP exporter Configuration: - Supports inline and external process filter configs - Whitelist/blacklist modes with regex patterns - Per-server customization via include files - Full OTLP configuration (endpoint, intervals, resource attributes) Docker Compose Stack: - OTEL Collector, Prometheus, Grafana - Pre-configured dashboard with system metrics - Ready-to-use testing environment Use Cases: - Production server monitoring - Container/K8s sidecar metrics - IoT/edge device monitoring - Headless systems where TUI is impractical This project was born from an OTEL export feature for bottom, but separated as it better serves as a dedicated metrics daemon. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..512535e --- /dev/null +++ b/README.md @@ -0,0 +1,228 @@ +# Symon + +**Lightweight system metrics exporter for OpenTelemetry** + +Symon is a dedicated daemon for collecting and exporting system metrics to OpenTelemetry collectors. Unlike traditional monitoring tools with TUI interfaces, Symon is purpose-built for headless operation, making it ideal for server environments. + +## Features + +- 🚀 **Lightweight & Fast** - Minimal resource footprint, optimized for server environments +- 📊 **Comprehensive Metrics** - CPU, memory, network, disk, processes, and temperature +- 🔍 **Smart Process Filtering** - Whitelist/blacklist with regex pattern support +- 📁 **External Config Files** - Server-specific process lists via include files +- 🔄 **OTLP Native** - Direct export to OpenTelemetry Collector via gRPC +- ⚙️ **Zero UI Overhead** - No terminal rendering, just pure metrics collection + +## Metrics Exported + +- **CPU**: Usage per core +- **Memory**: RAM and swap usage/total +- **Network**: RX/TX bytes per interface +- **Disk**: Usage and total space per mount +- **Processes**: Top 10 by CPU/Memory (with optional filtering) +- **Temperature**: System sensors (when available) + +All metrics follow OpenTelemetry semantic conventions with proper labels and descriptions. + +## Installation + +### From Source + +```bash +git clone https://github.com/battilo/symon.git +cd symon +cargo build --release +sudo cp target/release/symon /usr/local/bin/ +``` + +### Binary Release + +Download the latest release from [GitHub Releases](https://github.com/battilo/symon/releases). + +## Quick Start + +1. **Create a configuration file** (`symon.toml`): + +```toml +collection_interval_secs = 5 + +[otlp] +endpoint = "http://localhost:4317" +export_interval_secs = 10 +service_name = "symon" + +[metrics] +cpu = true +memory = true +network = true +disk = true +processes = true +temperature = true +``` + +2. **Run Symon**: + +```bash +symon --config symon.toml +``` + +3. **View metrics** in your observability stack (Prometheus + Grafana) + +## Configuration + +### Basic Configuration + +```toml +# How often to collect metrics (seconds) +collection_interval_secs = 5 + +[otlp] +# OpenTelemetry Collector endpoint +endpoint = "http://localhost:4317" + +# How often to export metrics (seconds) +export_interval_secs = 10 + +# Service identification +service_name = "symon" +service_version = "0.1.0" + +# Custom resource attributes +[otlp.resource_attributes] +environment = "production" +datacenter = "us-east-1" +host = "server-01" +``` + +### Metrics Selection + +```toml +[metrics] +cpu = true # CPU usage per core +memory = true # RAM and swap +network = true # Network interfaces +disk = true # Disk usage +processes = true # Top 10 processes +temperature = true # System temperatures +``` + +### Process Filtering + +Monitor only specific processes to reduce cardinality: + +**Option 1: Inline Configuration** + +```toml +[metrics.process_filter] +filter_mode = "whitelist" # or "blacklist" + +# Substring match (case-insensitive) +names = ["nginx", "postgres", "redis"] + +# Regex patterns (case-sensitive) +patterns = [ + "^node-v[0-9]+", # Node.js with version + "java.*MyApplication", # Java with specific class + "^gunicorn: worker \\[.*\\]" # Gunicorn workers +] + +# Specific PIDs +pids = [1234, 5678] +``` + +**Option 2: External File (recommended for multiple servers)** + +```toml +[metrics.process_filter] +include = "processes.toml" # or "/etc/symon/processes.toml" +``` + +`processes.toml`: +```toml +filter_mode = "whitelist" +names = ["nginx", "postgres"] +patterns = ["^docker-.*"] +``` + +This allows different process lists per server while keeping the main config identical. + +## Docker Compose Testing Stack + +A complete observability stack is provided for testing: + +```bash +cd docker-compose +docker-compose up -d +``` + +This starts: +- **OTEL Collector** (ports 4317/4318) +- **Prometheus** (port 9090) +- **Grafana** (port 3000, admin/admin) + +Then run Symon: + +```bash +symon -c docker-compose/symon-config-example.toml +``` + +Access Grafana at http://localhost:3000 to view the pre-configured "System Overview" dashboard. + +## Systemd Service + +Create `/etc/systemd/system/symon.service`: + +```ini +[Unit] +Description=Symon - System Metrics Exporter +After=network.target + +[Service] +Type=simple +User=symon +ExecStart=/usr/local/bin/symon --config /etc/symon/symon.toml +Restart=on-failure +RestartSec=5s + +[Install] +WantedBy=multi-user.target +``` + +Enable and start: + +```bash +sudo systemctl enable symon +sudo systemctl start symon +sudo systemctl status symon +``` + +## Comparison with Bottom + +Symon was originally developed as an OpenTelemetry export feature for [bottom](https://github.com/ClementTsang/bottom), but was split into a separate project as it better serves as a dedicated metrics daemon rather than a TUI tool extension. + +| Feature | Bottom | Symon | +|---------|--------|-------| +| **Purpose** | Interactive TUI monitor | Headless metrics exporter | +| **UI** | Rich terminal interface | None (daemon only) | +| **Resource Usage** | Higher (rendering) | Minimal (no UI) | +| **OTEL Export** | Optional feature | Core purpose | +| **Process Filtering** | UI-based | Config-based with regex | +| **Use Case** | Developer workstations | Production servers | + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +## License + +Licensed under either of: + +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) +- MIT license ([LICENSE-MIT](LICENSE-MIT)) + +at your option. + +## Acknowledgments + +- Inspired by [bottom](https://github.com/ClementTsang/bottom) by Clement Tsang +- Built with [OpenTelemetry](https://opentelemetry.io/) and [sysinfo](https://github.com/GuillaumeGomez/sysinfo)