twMQTTAgent

twMQTTAgent is a lightweight, cross-platform system monitoring agent written in Go. It collects system metrics (CPU, Memory, Load, Network, Processes) and publishes them to an MQTT broker in JSON format. It is designed as a modern extension for the TWSNMP series.

日本語の説明

---

Features

• System Metrics Monitoring: Gathers real-time performance indicators:
  • CPU usage (%)
  • Memory usage (%)
  • Load average
  • Network Traffic (Sent/Received bytes, Tx/Rx speed)
  • Active process count
• Network Interface Statistics: Gathers detailed adapter statistics (MTU, MAC address, operational status, errors, drops, packets sent/received) when -if-interval is set.
• ARP Table Monitoring: Periodically dumps the ARP table when -arp-interval is set.
• MQTT Integration: Publishes all collected telemetry data as JSON payloads to a specified MQTT broker.
• Cross-Platform: Works on Windows, Linux, and macOS.

Configuration & Usage

twMQTTAgent is configured using command-line flags.

CLI Flags

Flag	Default	Description
-broker	tcp://localhost:1883	MQTT broker URL (e.g., tcp://192.168.1.1:1883)
-client-id	twMQTTAgent	MQTT client ID
-topic	twMQTTAgent	Base MQTT topic prefix. The hostname and message type are appended (e.g., <topic>/Monitor/<hostname>)
-interval	30	Publish interval for system metrics (Monitor) in seconds
-if-interval	0	Publish interval for interface stats (IF) in seconds (0 to disable)
-arp-interval	0	Publish interval for ARP table (Arp) in seconds (0 to disable)
-user		MQTT username (optional)
-password		MQTT password (optional)
-hostname		Hostname used in topic and payload (defaults to system hostname if empty)

Running the Agent

# Basic usage sending metrics every 60 seconds
./twMQTTAgent -broker tcp://192.168.1.50:1883 -topic myhome/monitor -interval 60

# Running with interface and ARP monitoring enabled
./twMQTTAgent -broker tcp://192.168.1.50:1883 -if-interval 300 -arp-interval 600

---

Development & Build

This project uses mise for tool versioning and task runner workflows.

Prerequisites

• Go 1.21+

Build Commands

Using go toolchain directly:

# Build for local platform
go build -o twMQTTAgent

Using mise:

# Run locally for testing
mise run run

# Build for current host architecture
mise run build:local

# Cross-compile for Windows and Linux
mise run build:all

---

JSON Payload Formats

System Metrics (Topic: <topic>/Monitor/<hostname>)

{
  "time": "2026-07-02T05:28:08+09:00",
  "host": "my-pc-name",
  "cpu": 12.5,
  "memory": 53.1,
  "load": 1.45,
  "sent": 1024,
  "recv": 2048,
  "tx_speed": 0.15,
  "rx_speed": 0.30,
  "process": 120
}

Interface Statistics (Topic: <topic>/IF/<hostname>)

{
  "time": "2026-07-02T05:28:08+09:00",
  "host": "my-pc-name",
  "interfaces": [
    {
      "index": 1,
      "name": "eth0",
      "mtu": 1500,
      "mac": "00:11:22:33:44:55",
      "status": "up",
      "addrs": ["192.168.1.100/24"],
      "bytes_recv": 2048,
      "bytes_sent": 1024,
      "packets_recv": 20,
      "packets_sent": 15,
      "err_in": 0,
      "err_out": 0,
      "drop_in": 0,
      "drop_out": 0
    }
  ]
}

ARP Table (Topic: <topic>/Arp/<hostname>)

{
  "time": "2026-07-02T05:28:08+09:00",
  "host": "my-pc-name",
  "arp": [
    {
      "ip": "192.168.1.1",
      "mac": "00:11:22:33:44:55",
      "interface": "eth0",
      "type": "dynamic"
    }
  ]
}

---

License

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