toolbox

README

toolbox

Middleware toolbox provides health chcek, pprof, profile and statistic services for Macaron.

API Reference

Installation

go get gitea.com/macaron/toolbox

Usage

// main.go
import (
	"gitea.com/macaron/macaron"
	"gitea.com/macaron/toolbox"
)

func main() {
  	m := macaron.Classic()
  	m.Use(toolbox.Toolboxer(m))
	m.Run()
}

Open your browser and visit http://localhost:4000/debug to see the effects.

Options

toolbox.Toolboxer comes with a variety of configuration options:

type dummyChecker struct {
}

func (dc *dummyChecker) Desc() string {
	return "Dummy checker"
}

func (dc *dummyChecker) Check() error {
	return nil
}

// ...
m.Use(toolbox.Toolboxer(m, toolbox.Options{
	URLPrefix:			"/debug",			// URL prefix for toolbox dashboard
	HealthCheckURL:		"/healthcheck", 	// URL for health check request
	HealthCheckers: []HealthChecker{
		new(dummyChecker),
	},										// Health checkers
	HealthCheckFuncs: []*toolbox.HealthCheckFuncDesc{
		&toolbox.HealthCheckFuncDesc{
			Desc: "Database connection",
			Func: func() error { return "OK" },
		},
	},										// Health check functions
	DisableDebug:		false,				// Turns off all debug functionality when true
	PprofURLPrefix:		"/debug/pprof/", 	// URL prefix of pprof
	ProfileURLPrefix:	"/debug/profile/", 	// URL prefix of profile
	ProfilePath:		"profile",			// Path store profile files
}))
// ...

Route Statistic

Toolbox also comes with a route call statistic functionality:

import (
	"os"
	"time"
	//...
	"gitea.com/macaron/toolbox"
)

func main() {
	//...
	m.Get("/", func(t toolbox.Toolbox) {
		start := time.Now()
		
		// Other operations.
		
		t.AddStatistics("GET", "/", time.Since(start))
	})
	
	m.Get("/dump", func(t toolbox.Toolbox) {
		t.GetMap(os.Stdout)
	})
}

Output take from test:

+---------------------------------------------------+------------+------------------+------------------+------------------+------------------+------------------+
| Request URL                                       | Method     | Times            | Total Used(s)    | Max Used(μs)     | Min Used(μs)     | Avg Used(μs)     |
+---------------------------------------------------+------------+------------------+------------------+------------------+------------------+------------------+
| /api/user                                         | POST       |                2 |         0.000122 |       120.000000 |         2.000000 |        61.000000 |
| /api/user                                         | GET        |                1 |         0.000013 |        13.000000 |        13.000000 |        13.000000 |
| /api/user                                         | DELETE     |                1 |         0.000001 |         1.400000 |         1.400000 |         1.400000 |
| /api/admin                                        | POST       |                1 |         0.000014 |        14.000000 |        14.000000 |        14.000000 |
| /api/user/unknwon                                 | POST       |                1 |         0.000012 |        12.000000 |        12.000000 |        12.000000 |
+---------------------------------------------------+------------+------------------+------------------+------------------+------------------+------------------+

License

This project is under Apache v2 License. See the LICENSE file for the full license text.

Documentation

Overview

Package toolbox is a middleware that provides health check, pprof, profile and statistic services for Macaron.

Index

• func DumpGCSummary(w io.Writer)
• func DumpMemProf(w io.Writer)
• func StartCPUProfile() error
• func StopCPUProfile() error
• func Toolboxer(m *macaron.Macaron, options ...Options) macaron.Handler
• func Version() string
• type HealthCheckFunc
• type HealthCheckFuncDesc
• type HealthChecker
• type Options
• type Statistics
• type Toolbox
• type URLMapInfo
• type UrlMap
  • func (m *UrlMap) AddStatistics(requestMethod, requestUrl string, requesttime time.Duration)
  • func (m *UrlMap) GetMap(w io.Writer)
  • func (m *UrlMap) JSON(w io.Writer)

Functions

func DumpGCSummary

func DumpGCSummary(w io.Writer)

DumpGCSummary dumps GC information to io.Writer

func DumpMemProf

func DumpMemProf(w io.Writer)

DumpMemProf dumps memory profile in pprof.

func StartCPUProfile

func StartCPUProfile() error

StartCPUProfile starts CPU profile monitor.

func StopCPUProfile

func StopCPUProfile() error

StopCPUProfile stops CPU profile monitor.

func Toolboxer

func Toolboxer(m *macaron.Macaron, options ...Options) macaron.Handler

Toolboxer is a middleware provides health check, pprof, profile and statistic services for your application.

func Version

func Version() string

Types

type HealthCheckFunc

type HealthCheckFunc func() error

HealthCheckFunc represents a callable function for health check.

type HealthCheckFuncDesc

type HealthCheckFuncDesc struct {
	Desc string
	Func HealthCheckFunc
}

HealthCheckFunc represents a callable function for health check with description.

type HealthChecker

type HealthChecker interface {
	Desc() string
	Check() error
}

HealthChecker represents a health check instance.

type Options

type Options struct {
	// URL prefix for toolbox dashboard. Default is "/debug".
	URLPrefix string
	// URL for health check request. Default is "/healthcheck".
	HealthCheckURL string
	// Health checkers.
	HealthCheckers []HealthChecker
	// Health check functions.
	HealthCheckFuncs []*HealthCheckFuncDesc
	// URL for URL map json. Default is "/urlmap.json".
	URLMapPrefix string
	// DisableDebug turns off all debug functionality.
	DisableDebug bool
	// URL prefix of pprof. Default is "/debug/pprof/".
	PprofURLPrefix string
	// URL prefix of profile. Default is "/debug/profile/".
	ProfileURLPrefix string
	// Path store profile files. Default is "profile".
	ProfilePath string
}

Options represents a struct for specifying configuration options for the Toolbox middleware.

type Statistics

type Statistics struct {
	RequestUrl string
	RequestNum int64
	MinTime    time.Duration
	MaxTime    time.Duration
	TotalTime  time.Duration
}

Statistics struct

type Toolbox

type Toolbox interface {
	AddHealthCheck(HealthChecker)
	AddHealthCheckFunc(string, HealthCheckFunc)
	AddStatistics(string, string, time.Duration)
	GetMap(io.Writer)
	JSON(io.Writer)
}

Toolbox represents a tool box service for Macaron instance.

type URLMapInfo

type URLMapInfo struct {
	URL       string  `json:"url"`
	Method    string  `json:"method"`
	Times     int64   `json:"times"`
	TotalUsed float64 `json:"total_used"`
	MaxUsed   float64 `json:"max_used"`
	MinUsed   float64 `json:"min_used"`
	AvgUsed   float64 `json:"avg_used"`
}

type UrlMap

type UrlMap struct {
	LengthLimit int // limit the urlmap's length if it's equal to 0 there's no limit
	// contains filtered or unexported fields
}

UrlMap contains several statistics struct to log different data

func (*UrlMap) AddStatistics

func (m *UrlMap) AddStatistics(requestMethod, requestUrl string, requesttime time.Duration)

add statistics task. it needs request method, request url and statistics time duration

func (*UrlMap) GetMap

func (m *UrlMap) GetMap(w io.Writer)

put url statistics result in io.Writer

func (*UrlMap) JSON

func (m *UrlMap) JSON(w io.Writer)