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
- type Setting
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HookGlobalZeroLog ¶
HookGlobalZeroLog install zerolog as internal logger of Gin. We can use zerolog to output information like requested URLs, response code, latency, etc.
func HookPrometheus ¶
SetPrometheusToGin allow integration of Prometheus to /metrics path.
func InitGlobalZeroLog ¶
InitGlobalZeroLog initialize global zerolog.log instance with default configuration. It also sets global zerolog settings.
func NewGin ¶
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 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 ¶
NewSetting initializes a setting object with default values.
Source Files