metrics

README

go-metrics

Health and Metrics controller and web server library for Go

Usage with example

package example

import (
	"math/rand"

	"github.com/randlabs/go-metrics"
)

func main() {
	// Create a new health & metrics controller with a web server
	srvOpts := metrics.Options{
		Address:             "127.0.0.1",
		Port:                3000,
		HealthCallback:      healthCallback, // Setup our health check callback
		EnableDebugProfiles: true,
		IncludeCORS:         true,
		DisableClientCache:  true,
	}
	mc, err := metrics.CreateController(srvOpts)
	if err != nil {
		// handle error
	}

	// Create a custom prometheus counter
	err = mc.CreateCounterWithCallback(
		"random_counter", "A random counter",
		func() float64 {
			// Return the counter value.
			// The common scenario is to have a shared set of variables you regularly update with the current
			// state of your application.
			return rand.Float64()
		},
	)

	// Start health & metrics web server
	err = mc.Start()
	if err != nil {
		// handle error
	}

	// your app code may go here

	// Stop health & metrics web server before quitting
	mc.Destroy()
}

// Health output will be in JSON format.
type exampleHealthOutput struct {
	Status  string `json:"status"`
}

// Our health callback routine.
func healthCallback() string {
	state := exampleHealthOutput{
		Status: "ok",
	}

	j, _ := json.Marshal(state)
	return string(j)
}

License

See LICENSE file for details.

Documentation

Index

• type Controller
  • func CreateController(options Options) (*Controller, error)
  • func (mws *Controller) CreateCounterVecWithCallback(name string, help string, variableLabels []string, subItems VectorMetric) error
  • func (mws *Controller) CreateCounterWithCallback(name string, help string, handler ValueHandler) error
  • func (mws *Controller) CreateGaugeVecWithCallback(name string, help string, variableLabels []string, subItems VectorMetric) error
  • func (mws *Controller) CreateGaugeWithCallback(name string, help string, handler ValueHandler) error
  • func (mws *Controller) Destroy()
  • func (mws *Controller) Registry() *prometheus.Registry
  • func (mws *Controller) Start() error
• type HealthCallback
• type Options
• type ValueHandler
• type VectorMetric

Types

type Controller

type Controller struct {
	// contains filtered or unexported fields
}

Controller holds details about a metrics monitor instance.

func CreateController

func CreateController(options Options) (*Controller, error)

CreateController initializes and creates a new controller

func (*Controller) CreateCounterVecWithCallback

func (mws *Controller) CreateCounterVecWithCallback(
	name string, help string, variableLabels []string, subItems VectorMetric,
) error

CreateCounterVecWithCallback creates a vector of counters metric where their data are populated by calling a callback

func (*Controller) CreateCounterWithCallback

func (mws *Controller) CreateCounterWithCallback(name string, help string, handler ValueHandler) error

CreateCounterWithCallback creates a single counter metric where its data is populated by calling a callback

func (*Controller) CreateGaugeVecWithCallback

func (mws *Controller) CreateGaugeVecWithCallback(
	name string, help string, variableLabels []string, subItems VectorMetric,
) error

CreateGaugeVecWithCallback creates a vector of gauges metric where their data are populated by calling a callback

func (*Controller) CreateGaugeWithCallback

func (mws *Controller) CreateGaugeWithCallback(name string, help string, handler ValueHandler) error

CreateGaugeWithCallback creates a single gauge metric where its data is populated by calling a callback

func (*Controller) Destroy

func (mws *Controller) Destroy()

Destroy destroys the monitor and stops the internal web server

func (*Controller) Registry

func (mws *Controller) Registry() *prometheus.Registry

Registry returns the prometheus registry object

func (*Controller) Start

func (mws *Controller) Start() error

Start starts the monitor's internal web server

type HealthCallback

type HealthCallback func() string

HealthCallback indicates a function that returns a string that will be returned as the output.

type Options

type Options struct {
	// If Server is provided, use this server instead of creating a new one.
	Server *webserver.Server

	// Server name to use when sending response headers. Defaults to 'metrics-server'.
	Name string

	// Address is the bind address to attach the internal web server.
	Address string

	// Port is the port number the internal web server will use.
	Port uint16

	// TLSConfig optionally provides a TLS configuration for use.
	TLSConfig *tls.Config

	// A callback to call if an error is encountered.
	ListenErrorHandler webserver.ListenErrorHandler

	// AccessToken is an optional access token required to access the status endpoints.
	AccessToken string

	// If RequestAccessTokenInHealth is enabled, access token checked also in '/health' endpoint.
	RequestAccessTokenInHealth bool

	// HealthCallback is a function that returns an object which, in turn, will be converted to JSON format.
	HealthCallback HealthCallback

	// Expose debugging profiles /debug/pprof endpoint.
	EnableDebugProfiles bool

	// Include Cache-Control headers in response to disable client-side caching.
	DisableClientCache bool

	// Include CORS headers in response.
	IncludeCORS bool

	// Middlewares additional set of middlewares for the endpoints.
	Middlewares []webserver.MiddlewareFunc
}

Options specifies metrics controller initialization options.

type ValueHandler

type ValueHandler func() float64

type VectorMetric

type VectorMetric []struct {
	Values  []string
	Handler ValueHandler
}