Systatus 🔎

Note: Systatus is currently in beta, and we are actively working on expanding functionality. Be sure to update frequently to get the latest features and improvements.

What is Systatus?

Systatus is a lightweight Go library inspired by Spring Boot's Actuator, designed to add system observability and monitoring endpoints to any Go application. It allows you to expose essential system information and application health metrics through HTTP routes, enabling quick insights and diagnostics. With just two lines of code, Systatus can provide your application with predefined routes to monitor metrics like CPU, memory, and disk usage, as well as application uptime and a simple health check.

• Quick start
• Systatys Options
• Available Handlers
  • /health
  • /env
  • /cpu
  • /disk
  • /mem
  • /uptime

Quickstart

Install Systatus in your go project:

go get github.com/gdegiorgio/systatus

Then import and simply use the Enable method

package main

import (
	"fmt"
	"net/http"
	"github.com/gdegiorgio/systatus"
)

func main() {
	opts := SystatusOptions{ Prefix : "/dev"}
	systatus.Enable(opts)
	http.ListenAndServe(":8080", nil)
}

Systatus Options

Option	Type	Default	Description
Prefix	string	""	Specifies a URL prefix for all systatus endpoints. For example, setting Prefix: "/dev" results in /dev/health.
ExposeEnv	boolean	false	Enables the /env endpoint, exposing environment variables. Use cautiously as this may reveal sensitive data.
PrettyLogger	boolean	false	If set to true, replaces JSON-formatted logging with human-readable plain text logs.
HealthHandlerOpts	/health options	nil	Configuration for the /health handler
CPUHandlerOpts	/cpu options	nil	Configuration for the /cpu handler
EnvHandlerOpts	/env options	nil	Configuration for the /env handler
DiskHandlerOpts	/disk options	nil	Configuration for the /disk handler
MemHandlerOpts	/mem options	nil	Configuration for the /mem handler
UptimeHandlerOpts	/uptime options	nil	UConfiguration for the /uptime handler

Notes:

• Options with nil defaults: These options are optional and customizable through their respective configurations. Reference specific handler documentation (linked in the table) for details.
• Logging Behavior: Setting PrettyLogger to true is recommended for debugging purposes but might increase log size due to less structured output.
• Prefix Best Practices: Use Prefix to isolate endpoints in shared environments, e.g., /api/systatus.

Available Handlers

/health

This endpoint is used to report system health status.

Options

Option	Type	Default	Description
Healtcheck	func(w http.ResponseWriter, r *http.Request)	nil	Allows users to define a custom health check function. This function overrides the default /health handler logic and must write the HTTP response directly.
Middlewares	[]func(next http.HandlerFunc) http.HandlerFunc	[]	A list of middleware functions applied to the request pipeline. Each middleware wraps the handler, enabling custom preprocessing or postprocessing of requests.

HealthResponse

Option	Type	Description
status	string	Current System status

{
  "status" : "HEALTHY"
}

/env

This endpoint is used to expose system environment variables.

Note: This endpoint will not be exposed by default unless you set ExposeEnv to true in SystatusOptions.

Options

Option	Type	Default	Description
SensitiveKeys	[]string	[]	A list of key names whose values should be masked in logs or responses to prevent exposure of sensitive data.
Middlewares	[]func(next http.HandlerFunc) http.HandlerFunc	[]	A list of middleware functions applied to the request pipeline. Each middleware wraps the handler, enabling custom preprocessing or postprocessing of requests.

EnvResponse

Field	Type	Description
env	map[string]string	A map representing system environment variable

{
  "env" : {
    "GO_VERSION": "1.23.0",
    "APIKEY" : "************************"
  }
}

/cpu

This endpoint is not available yet and will soon be implemented.

/mem

This endpoint is used to retrieve runtime memory usage statistics

Options

Option	Type	Default	Description
SensitiveKeys	[]string	[]	A list of key names whose values should be masked in logs or responses to prevent exposure of sensitive data.
Middlewares	[]func(next http.HandlerFunc) http.HandlerFunc	[]	A list of middleware functions applied to the request pipeline. Each middleware wraps the handler, enabling custom preprocessing or postprocessing of requests.

MemResponse

Field	Type	Description
TotalAlloc	uint64	The cumulative bytes allocated and freed by the application.
Alloc	uint64	The current number of bytes allocated in heap objects.
Sys	uint64	The total bytes of memory obtained from the operating system (includes heap, stack, and other uses).

{
  "total_alloc": 1048576,
  "alloc": 524288,
  "sys": 2097152
}

/uptime

This endpoint is used to report system uptime and current system time.

Options

Option	Type	Default	Description
Middlewares	[]func(next http.HandlerFunc) http.HandlerFunc	[]	A list of middleware functions applied to the request pipeline. Each middleware wraps the handler, enabling custom preprocessing or postprocessing of requests.

UptimeResponse

Systime string The current system time in a human-readable format (e.g., ISO 8601). Uptime string The server's uptime since it was started, formatted as hh:mm:ss.

Field	Type	Description
Systime	string	The current system time in RFC3339 format
Uptime	float64	The server's uptime since it was started, in milliseconds.

{
  "systime": "2024-11-27T20:58:09+01:00",
  "uptime": 2817580
}