Skip to content

Latest commit

 

History

History
195 lines (129 loc) · 10.5 KB

README.md

File metadata and controls

195 lines (129 loc) · 10.5 KB
Raw

Systatus 🔎

Go Version

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.

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
}