gregson

README

Gregson: A REST API Server Builder

This library provides a set of functions to create an web app, which provides functionalities that can be accessed via a command line client (behave like awscli), or works with an HTML5 Single Page Application.

Gregson does not aim to be a "framework" but a utility library to use existing popular Go libraries, with a set of configured settings to make web app reasonable to diagnose after it's deployed in production.

Gregson is built on the popular Golang libraries like Gin, Zerolog, and Prometheus. Given it's not framework, it directly expose data structures from the libraries it references, with a purpose to avoid introduce new concepts in code.

Quick start

Gregson is built upon Go 1.14 or above, supporting go.mod mode only. To reference Gregson, run commands below from your Go project.

    go get -v https://github.com/fuzhouch/gregson

A minimized example looks like below. It forces applying global logging settings via InitGlobalZeroLog(), then creates an gin.Engine object with zerolog and Prometheus hooked. Once g.Run() is called, developer can immediately see JSON log written in io.Stderr. They can also use /metrics path to access Prometheus metrics.

package main
import (
    "io"

    "github.com/gin-gonic/go"
    "github.com/fuzhouch/gregson"
)

func main() {
    gregson.InitGlobalZeroLog(io.Stderr)
    s := gregson.NewSetting()
    g := gregson.NewGin(s) // Zerolog and Prometheus are integrated.

    g.GET("/", func(c *gin.Context) {
        c.String(http.StatusOK, "")
    })
    g.Run() // Listen and serve on 0.0.0.0:8080
}

Developer can use gregson.Setting structure to configure how gin.Engine object is created.

About the name

The name of this library, "Gregson", refers to Tobias Gregson, the Scotland Yard inspector who worked with Sherlock Holmes in A Study of Scalet case. He created his own theory to explain what happens, though mostly wrong, which was named by Sherlock Holmes as "the smartest detective in Scottland Yard".

If you find it hard to customize... yes, it's by design

I pick name "Gregson" to reflect what we may find in this library: it has its own attitude to select library and options which is needed in web development scenario, even if this is not "correct" to everyone. Customization is never part of design goals of Gregson.

For example, Gregson picks Gin as web framework and zerolog as logger. If a developer wants to use echo and logrus, don't submit a feature request or PR. This library will not offer any customization to adopt different frameworks. For same reason, if a developer want to change default log level (which is forced to be zerolog.Info), it will not be accepted either.

The best option for these requests, is to copy useful snippets from Gregson to your code base. It's completely allowed by MIT License.

Documentation

Index

• func HookGlobalZeroLog(r *gin.Engine)
• func HookPrometheus(r *gin.Engine, s *Setting)
• func InitGlobalZeroLog(toFile io.Writer) error
• func NewGin(s *Setting) *gin.Engine
• func NewZeroLog(toFile io.Writer) (zerolog.Logger, error)
• func SetGlobalZeroLogPolicy()
• func SetOffGlobalZeroLog()
• type JWTSetting
• type PromSetting
  • func (s *PromSetting) SetRegistry(r *prometheus.Registry)
• type Setting
  • func NewSetting(appName string) *Setting

Functions

func HookGlobalZeroLog

func HookGlobalZeroLog(r *gin.Engine)

HookGlobalZeroLog install zerolog as internal logger of Gin. We can use zerolog to output information like requested URLs, response code, latency, etc.

func HookPrometheus

func HookPrometheus(r *gin.Engine, s *Setting)

SetPrometheusToGin allow integration of Prometheus to /metrics path.

func InitGlobalZeroLog

func InitGlobalZeroLog(toFile io.Writer) error

InitGlobalZeroLog initialize global zerolog.log instance with default configuration. It also sets global zerolog settings.

func NewGin

func NewGin(s *Setting) *gin.Engine

NewApp function creates an gregson web app. An Gregson web app is designed to build a REST API server that can work with a command line client or web client. The server is configured with a set of integrations, to make sure the server meets engineering requirements like monitoring, logging, etc.

Besides, Gregson engine configured some default endpoints.

- POST /login provides a form with username and password. - GET /metrics provides Prometheus integration

func NewZeroLog

func NewZeroLog(toFile io.Writer) (zerolog.Logger, error)

func SetGlobalZeroLogPolicy

func SetGlobalZeroLogPolicy()

SetGlobalZeroLogPolicy sets default zerolog settings used by Gregson. The following policy are enforced:

1. Always use RFC3339 format ("2006-01-02T15:04:05Z07:00") 2. Timestamp returns UTC. 3. Prints only INFO level logs or above. 4. Sampling is disabled.

The reason for #1 and #2 is Gregson tries to make service log easy to read when distributed across multiple regions.

Special notes for #3: Gregson explicitly disallows developers apply different logging levels for dev and production enviornment. This is intentionally forbids a practice, that developers expect they can use dev environment to re-produce an issue reported in production, but with more logging info internally. This approach is proven not working for Internet oriented services, because many issues are triggerred only under high load which can be pretty difficult to simulate in dev environment. A correct practice, is to make sure service always generate identical information no matter in which environment.

#4 is set by almost same reason with #3. Sampling sacrifaces diagnose feasibility to get smaller file size. This is usually not worthy in production environment.

func SetOffGlobalZeroLog

func SetOffGlobalZeroLog()

SetOffGlobalZeroLog configures global zerolog to discard messages. This is useful when writing tests, but do not use in production.

Types

type JWTSetting

type JWTSetting struct {
}

type PromSetting

type PromSetting struct {
	Namespace      string
	Subsystem      string
	Path           string
	Ignore         []string
	CreateRegistry bool
	// contains filtered or unexported fields
}

PromSetting specifies how to create a new registry.

func (*PromSetting) SetRegistry

func (s *PromSetting) SetRegistry(r *prometheus.Registry)

SetRegistry allow using a customized registry instead of default registry used by Promethues when creating Prometheus integration. This is useful in scenarios that developers must register registry multiple times, for example, unit test.

type Setting

type Setting struct {
	AppName    string
	Prometheus PromSetting
	JWT        JWTSetting
}

Setting specifies configuration when building web app.

func NewSetting

func NewSetting(appName string) *Setting

NewSetting initializes a setting object with default values.