debug

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2020 License: MIT Imports: 14 Imported by: 1

README

go-debug build status

Conditional debug logging for Go libraries.

View the docs.

Installation

$ go get github.com/tj/go-debug

Example

DEBUG=* go run ./example/readme/index.go

21:16:16.870 4us   app-name:main - sending mail
21:16:16.870 765ns app-name:main - sending mail
21:16:16.870 542ns app-name:main - send email to tobi@segment.io
21:16:16.870 455ns app-name:main - send email to loki@segment.io
21:16:16.870 485ns app-name:main - send email to jane@segment.io
21:16:16.870 50us  app-name:sibling - hi
21:16:16.870 846ns app-name:main:helper - hi
21:16:17.371 501ms app-name:main - sending mail
21:16:17.371 1us   app-name:main - sending mail
21:16:17.371 694ns app-name:main - send email to tobi@segment.io
21:16:17.371 667ns app-name:main - send email to loki@segment.io
21:16:17.371 573ns app-name:main - send email to jane@segment.io
21:16:17.371 501ms app-name:sibling - hi
21:16:17.371 501ms app-name:main:helper - hi
21:16:17.871 500ms app-name:main - sending mail
21:16:17.871 1us   app-name:main - sending mail
21:16:17.871 761ns app-name:main - send email to tobi@segment.io
21:16:17.871 583ns app-name:main - send email to loki@segment.io
21:16:17.871 592ns app-name:main - send email to jane@segment.io
21:16:17.871 500ms app-name:sibling - hi
21:16:17.871 1s    app-name:main:helper - hi
21:16:18.371 500ms app-name:main - sending mail
21:16:18.371 865ns app-name:main - sending mail
21:16:18.371 601ns app-name:main - send email to tobi@segment.io
21:16:18.371 558ns app-name:main - send email to loki@segment.io
21:16:18.371 547ns app-name:main - send email to jane@segment.io
21:16:18.371 500ms app-name:sibling - hi
21:16:18.371 1s    app-name:main:helper - hi
21:16:18.874 502ms app-name:main - sending mail
21:16:18.874 26us  app-name:main - sending mail
21:16:18.874 896ns app-name:main - send email to tobi@segment.io
21:16:18.874 716ns app-name:main - send email to loki@segment.io
21:16:18.874 652ns app-name:main - send email to jane@segment.io
21:16:18.874 503ms app-name:sibling - hi
21:16:18.874 2s    app-name:main:helper - hi

A timestamp and two deltas are displayed. The timestamp consists of hour, minute, second and microseconds. The left-most delta is relative to the previous debug call of any name, followed by a delta specific to that debug function. These may be useful to identify timing issues and potential bottlenecks.

The DEBUG environment variable

Executables often support --verbose flags for conditional logging, however libraries typically either require altering your code to enable logging, or simply omit logging all together. go-debug allows conditional logging to be enabled via the DEBUG environment variable, where one or more patterns may be specified.

For example suppose your application has several models and you want to output logs for users only, you might use DEBUG=models:user. In contrast if you wanted to see what all database activity was you might use DEBUG=models:*, or if you're love being swamped with logs: DEBUG=*. You may also specify a list of names delimited by a comma, for example DEBUG=mongo,redis:*. If your swamped you can also start omitting namespaces ie: DEBUG=*,-mongo,-redis.

The name given should be the package name, however you can use whatever you like.

License

MIT

Development

Install:

  • yq - brew install yq
  • golines - go get -u github.com/segmentio/golines
  • golangci-lint - brew install golangci/tap/golangci-lint

Documentation

Index

Examples

Constants

View Source 
const (
	FieldKeyMsg       = "msg"
	FieldKeyNamespace = "namespace"
	FieldKeyTime      = "time"
	FieldKeyDelta     = "delta"
	FieldKeyError     = "debug_error"
)

Variables

View Source 
var (
	HAS_COLORS = true
	HAS_TIME   = true
)
View Source 
var SetHasColors = setBoolWithLock(func(isOn bool) {
	HAS_COLORS = isOn
})
View Source 
var SetHasTime = setBoolWithLock(func(isOn bool) {
	HAS_TIME = isOn
})

Functions

func BasicFormat added in v0.1.0 

func BasicFormat(ts string, delta string, ns string, msg string) string

func BuildNegativeMatches added in v0.1.0 

func BuildNegativeMatches(pattern string) (string, []string)

Find all negative namespaces and pull them out of the pattern.

But build a slice of negatives

example: pattern="*,-somenamespace"

Returns: "*", ["somenamespace"]

func BuildPattern added in v0.1.0 

func BuildPattern(pattern string) (string, []string)

func Disable 

func Disable()

Disable all pattern matching. This function is thread-safe.

func Enable 

func Enable(pattern string)

Enable the given debug `pattern`. Patterns take a glob-like form, for example if you wanted to enable everything, just use "*", or if you had a library named mongodb you could use "mongodb:connection", or "mongodb:*". Multiple matches can be made with a comma, for example "mongo*,redis*".

This function is thread-safe.

Example 
Enable("mongo:connection")
Enable("mongo:*")
Enable("foo,bar,baz")
Enable("*")

func RegExWrap added in v0.1.0 

func RegExWrap(pattern string) string

func SetCache added in v0.0.5 

func SetCache(cacheMinStr string) error

Initialize the namespace cache which defaults to 60 min lifespan

func SetFormatter added in v0.1.0 

func SetFormatter(f Formatter)

func SetWriter 

func SetWriter(w io.Writer)

SetWriter replaces the default of os.Stderr with `w`.

Types

type Debugger 

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

func Debug 

func Debug(name string) *Debugger

Debug creates a debug function for `name` which you call with printf-style arguments in your application or library.

Example 
var debug = Debug("single")

for {
	debug.Log("sending mail")
	debug.Log("send email to %s", "tobi@segment.io")
	debug.Log("send email to %s", "loki@segment.io")
	debug.Log("send email to %s", "jane@segment.io")
	time.Sleep(500 * time.Millisecond)
}

func (*Debugger) Log 

func (dbg *Debugger) Log(args ...interface{})

func (*Debugger) Spawn 

func (dbg *Debugger) Spawn(ns string) *Debugger

func (*Debugger) WithField added in v0.1.0 

func (dbg *Debugger) WithField(key string, value interface{}) *Debugger

func (*Debugger) WithFields added in v0.1.0 

func (dbg *Debugger) WithFields(fields map[string]interface{}) *Debugger

type Fields added in v0.1.0 

type Fields map[string]interface{}

type Finalized added in v0.1.0 

type Finalized struct {
	Fields     Fields
	Namespace  string
	TimeString string
	Delta      string
}

type Formatter added in v0.1.0 

type Formatter interface {
	Format(*Debugger, string) string
	GetHasFieldsOnly() bool
}

highly inspired by logrus

type IDebugger added in v0.1.0 

type IDebugger interface {
	Log(...interface{})
	Spawn(ns string) *Debugger
	WithFields(fields map[string]interface{}) *Debugger
	WithField(key string, value interface{}) *Debugger
}

type JSONFormatter added in v0.1.0 

type JSONFormatter struct {
	// TimestampFormat sets the format used for marshaling timestamps.
	TimestampFormat string

	// DisableHTMLEscape allows disabling html escaping in output
	DisableHTMLEscape bool

	// CallerPrettyfier can be set by the user to modify the content
	// of the function and file keys in the json data when ReportCaller is
	// activated. If any of the returned value is the empty string the
	// corresponding key will be removed from json fields.
	CallerPrettyfier func(*runtime.Frame) (function string, file string)

	// PrettyPrint will indent all json logs
	PrettyPrint bool
}

JSONFormatter formats logs into parsable json

func (*JSONFormatter) Format added in v0.1.0 

func (f *JSONFormatter) Format(dbg *Debugger, msg string) string

func (*JSONFormatter) GetHasFieldsOnly added in v0.1.0 

func (f *JSONFormatter) GetHasFieldsOnly() bool

type TextFormatter added in v0.1.0 

type TextFormatter struct {
	HasColor         bool
	ForceQuote       bool
	QuoteEmptyFields bool
	DisableQuote     bool
	HasFieldsOnly    bool
	SortingFunc      func(keys []string)
}

func (*TextFormatter) Format added in v0.1.0 

func (t *TextFormatter) Format(dbg *Debugger, msg string) string

func (*TextFormatter) GetHasFieldsOnly added in v0.1.0 

func (t *TextFormatter) GetHasFieldsOnly() bool

Source Files

View all Source files

Directories

Path Synopsis
example
multiple command
multipleFieldsOnly command
multipleJson command
multipleLazy command
readme command
readme/pkg
rootDebug
single command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.