goth

README

Goth

Functionality

• Exposes an HTTP handler that retrieves health status of the application
• Implements some generic checkers for the following services:
  • RabbitMQ
  • PostgreSQL
  • Redis
  • HTTP
  • MongoDB
  • MySQL
  • gRPC
  • Memcached

Usage

The library exports Handler and HandlerFunc functions which are fully compatible with net/http.

Additionally, library exports Measure function that returns summary status for all the registered health checks, so it can be used in non-HTTP environments.

Handler

package main

import (
	"context"
	"net/http"
	"time"

	"github.com/h-varmazyar/goth"
	healthMysql "github.com/h-varmazyar/goth/checks/mysql"
    healthRabbit "github.com/h-varmazyar/goth/checks/rabbitmq"
)

func main() {
	// add some checks on instance creation
	h, _ := goth.New(goth.WithChecks(goth.Config{
		Name:      "mongodb",
		Timeout:   time.Second * 5,
		SkipOnErr: true,
		Check: func(ctx context.Context) error {
			// rabbitmq health check implementation goes here
			return nil
		}}, goth.Config{
		Name: "rabbitmq",
		Check: healthRabbit.New(healthRabbit.Config{
            DSN: "amqp://user:password@host:port",
        }),
	},
	))

	// and then add some more if needed
	h.Register(goth.Config{
		Name:      "mysql",
		Timeout:   time.Second * 2,
		SkipOnErr: false,
		Check: healthMysql.New(healthMysql.Config{
			DSN: "test:test@tcp(0.0.0.0:31726)/test?charset=utf8",
		}),
	})

	http.Handle("/status", h.Handler())
	http.ListenAndServe(":3000", nil)
}

HandlerFunc

package main

import (
	"context"
	"net/http"
	"time"

	"github.com/go-chi/chi"
	"github.com/h-varmazyar/goth"
	healthMysql "github.com/h-varmazyar/goth/checks/mysql"
    healthRabbit "github.com/h-varmazyar/goth/checks/rabbitmq"
)

func main() {
	// add some checks on instance creation
	h, _ := goth.New(goth.WithChecks(goth.Config{
		Name:      "rabbitmq",
		Timeout:   time.Second * 5,
		SkipOnErr: true,
		Check: healthRabbit.New(healthRabbit.Config{
          DSN: "amqp://user:password@host:port",
        })}, goth.Config{
		Name: "mongodb",
		Check: func(ctx context.Context) error {
			// mongo_db health check implementation goes here
			return nil
		},
	},
	))

	// and then add some more if needed
	h.Register(goth.Config{
		Name:      "mysql",
		Timeout:   time.Second * 2,
		SkipOnErr: false,
		Check: healthMysql.New(healthMysql.Config{
			DSN: "test:test@tcp(0.0.0.0:31726)/test?charset=utf8",
		}),
	})

	r := chi.NewRouter()
	r.Get("/status", h.HandlerFunc)
	http.ListenAndServe(":3000", nil)
}

For more examples please check here

API Documentation

GET /status

Get the health of the application.

• Method: GET
• Endpoint: /status
• Request:
• Params:
  • service_name: the name of registered service for getting status of certain service. this param is optional. if you want to get all services status ignore this parameter.

curl localhost:3000/status?service_name={name_of_registerd_check}

• Response:

HTTP/1.1 200 OK

{
  "status": "OK",
  "timestamp": "2017-01-01T00:00:00.413567856+033:00",
  "system": {
    "version": "go1.8",
    "goroutines_count": 4,
    "total_alloc_bytes": 21321,
    "heap_objects_count": 21323,
    "alloc_bytes": 234523
  }
}

HTTP custom code 509

{
  "status": "Partially Available",
  "timestamp": "2017-01-01T00:00:00.413567856+033:00",
  "failures": {
    "rabbitmq": "Failed during rabbitmq health check"
  },
  "system": {
    "version": "go1.8",
    "goroutines_count": 4,
    "total_alloc_bytes": 21321,
    "heap_objects_count": 21323,
    "alloc_bytes": 234523
  }
}

HTTP/1.1 503 Service Unavailable

{
  "status": "Unavailable",
  "timestamp": "2017-01-01T00:00:00.413567856+033:00",
  "failures": {
    "mongodb": "Failed during mongodb health check"
  },
  "system": {
    "version": "go1.8",
    "goroutines_count": 4,
    "total_alloc_bytes": 21321,
    "heap_objects_count": 21323,
    "alloc_bytes": 234523
  }
}

Contributing

• Fork it
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create new Pull Request

Documentation

Index

• type Check
• type CheckFunc
• type Component
• type Config
• type Health
  • func New(opts ...Option) (*Health, error)
  • func (h *Health) Handler() http.Handler
  • func (h *Health) HandlerFunc(w http.ResponseWriter, r *http.Request)
  • func (h *Health) Measure(ctx context.Context, serviceName string) Check
  • func (h *Health) Register(c Config) error
• type Option
  • func WithChecks(checks ...Config) Option
  • func WithComponent(component Component) Option
  • func WithMaxConcurrent(n int) Option
  • func WithSystemInfo() Option
  • func WithTracerProvider(tp trace.TracerProvider, instrumentationName string) Option
• type Status
• type System

Types

type Check

type Check struct {
	// Status is the check status.
	Status Status `json:"status"`
	// Timestamp is the time in which the check occurred.
	Timestamp time.Time `json:"timestamp"`
	// Failures holds the failed checks along with their messages.
	Failures map[string]string `json:"failures,omitempty"`
	// System holds information of the go process.
	*System `json:"system,omitempty"`
	// Component holds information on the component for which checks are made
	Component `json:"component"`
}

Check represents the health check response.

type CheckFunc

type CheckFunc func(context.Context) error

CheckFunc is the func which executes the check.

type Component

type Component struct {
	// Name is the name of the component.
	Name string `json:"name"`
	// Version is the component version.
	Version string `json:"version"`
}

Component descriptive values about the component for which checks are made

type Config

type Config struct {
	// Name is the name of the resource to be checked.
	Name string
	// Timeout is the timeout defined for every check.
	Timeout time.Duration
	// SkipOnErr if set to true, it will retrieve StatusOK providing the error message from the failed resource.
	SkipOnErr bool
	// Check is the func which executes the check.
	Check CheckFunc
}

Config carries the parameters to run the check.

type Health

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

Health is the health-checks container

func New

func New(opts ...Option) (*Health, error)

New instantiates and build new health check container

func (*Health) Handler

func (h *Health) Handler() http.Handler

Handler returns an HTTP handler (http.HandlerFunc).

func (*Health) HandlerFunc

func (h *Health) HandlerFunc(w http.ResponseWriter, r *http.Request)

HandlerFunc is the HTTP handler function.

func (*Health) Measure

func (h *Health) Measure(ctx context.Context, serviceName string) Check

Measure runs all the registered health checks and returns summary status

func (*Health) Register

func (h *Health) Register(c Config) error

Register registers a check config to be performed.

type Option

type Option func(*Health) error

Option is the health-container options type

func WithChecks

func WithChecks(checks ...Config) Option

WithChecks adds checks to newly instantiated health-container

func WithComponent

func WithComponent(component Component) Option

WithComponent sets the component description of the component to which this check refer

func WithMaxConcurrent

func WithMaxConcurrent(n int) Option

WithMaxConcurrent sets max number of concurrently running checks. Set to 1 if want to run all checks sequentially.

func WithSystemInfo

func WithSystemInfo() Option

WithSystemInfo enables the option to return system information about the go process.

func WithTracerProvider

func WithTracerProvider(tp trace.TracerProvider, instrumentationName string) Option

WithTracerProvider sets trace provider for the checks and instrumentation name that will be used for tracer from trace provider.

type Status

type Status string

Status type represents health status

const (
	StatusOK                 Status = "OK"
	StatusNotFound           Status = "Service not found"
	StatusPartiallyAvailable Status = "Partially Available"
	StatusUnavailable        Status = "Unavailable"
	StatusTimeout            Status = "Timeout during health check"
)

Possible health statuses

type System

type System struct {
	// Version is the go version.
	Version string `json:"version"`
	// GoroutinesCount is the number of the current goroutines.
	GoroutinesCount int `json:"goroutines_count"`
	// TotalAllocBytes is the total bytes allocated.
	TotalAllocBytes int `json:"total_alloc_bytes"`
	// HeapObjectsCount is the number of objects in the go heap.
	HeapObjectsCount int `json:"heap_objects_count"`
	// TotalAllocBytes is the bytes allocated and not yet freed.
	AllocBytes int `json:"alloc_bytes"`
}

System runtime variables about the go process.