A small tcp server for monitoring a node in a cluster
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Antonio De Lucreziis c86785ecdf feat: added temperature command 4 months ago
.github/workflows chore: updated github workflow 4 months ago
.gitignore initial commit 4 months ago
README.md feat: added temperature command 4 months ago
go.mod initial commit 4 months ago
main.go feat: added temperature command 4 months ago


Go Stats Server

This Go project implements a simple TCP server that responds to custom commands over an internal network. The server performs various system-related tasks and provides information such as CPU usage, memory status, network statistics, storage details, and system uptime.


The protocol supports the following commands:

  • cpu — returns the CPU usage percentage
  • memory — returns the memory usage in MB
  • network — returns the network usage in bytes
  • storage — returns the storage usage in GB
  • uptime — returns the system uptime in seconds
  • temperature — returns the CPU temperature of Big and Little cores in Celsius

[TODO: check if the command docs are correct]


  1. Build the Server:

    $ CGO_ENABLED=0 GOARCH=<arch> go build -a -ldflags '-s -w' -o ./out/stats-server main.go
  2. Run the Server:

    $ ./out/stats-server serve
  3. Connect to the Server: Use a TCP client to connect to the server on port 12345. You can send commands like "cpu", "memory", "network", "storage" or "uptime".

    Example using nc:

    $ time ( echo "cpu" | nc <hostname> 12345 )

    or directly using golang:

    conn, _ := net.Dial("tcp", "<hostname>:12345")
    data, _ := io.RealAll(conn)
    log.Printf("data: %s", data)

GitHub Actions Workflow

The included GitHub Actions workflow automates the build and release process. On each push to the main branch, the workflow builds the Go program, creates a GitHub release, and uploads the compiled binary as an artifact.

Self-Installing Binary

Assuming you have a cluster of machines, you can use the following commands to download, install and setup systemd services for the latest version of the binary on all nodes. You must have root access to all nodes.

$ parallel --nonall --slf nodes.txt 'mkdir -p cluster'
$ parallel --nonall --slf nodes.txt 'wget -qO- https://github.com/aziis98/go-stats-server/releases/latest/download/stats-server > ./cluster/stats-server'
$ parallel --nonall --slf nodes.txt 'chmod -v +x ./cluster/stats-server'

# setup systemd services on all nodes
$ parallel --nonall --slf nodes.txt './cluster/stats-server setup'

# setup systemd service on a single node
$ ssh root@<node>
$ cd cluster
$ ./stats-server setup

# trying out the new binary using netcat
$ time ( echo '<command>' | nc <node> 12345 )

# stop and disable the systemd service on all nodes
$ parallel --nonall --slf nodes.txt 'systemctl disable --now stats-server.service'