Skip to content

Commit ff67ccf

Browse files
author
Dean Karn
authored
Merge pull request #14 from go-playground/revamp
2 parents effffa9 + 366ff41 commit ff67ccf

33 files changed

+1277
-4240
lines changed

‎LICENSE‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2016 Go Experimental
3+
Copyright (c) 2018 Go Playground
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1818
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1919
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
2020
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21-
SOFTWARE.
21+
SOFTWARE.

‎README.md‎

Lines changed: 70 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,55 @@
11
## log
2-
<img align="right" src="https://raw.githubusercontent.com/go-playground/log/master/logo.png">![Project status](https://img.shields.io/badge/version-4.3.0-green.svg)
2+
<img align="right" src="https://raw.githubusercontent.com/go-playground/log/master/logo.png">![Project status](https://img.shields.io/badge/version-5.0.0-green.svg)
33
[![Build Status](https://semaphoreci.com/api/v1/joeybloggs/log/branches/master/badge.svg)](https://semaphoreci.com/joeybloggs/log)
44
[![Coverage Status](https://coveralls.io/repos/github/go-playground/log/badge.svg?branch=master)](https://coveralls.io/github/go-playground/log?branch=master)
55
[![Go Report Card](https://goreportcard.com/badge/github.com/go-playground/log)](https://goreportcard.com/report/github.com/go-playground/log)
66
[![GoDoc](https://godoc.org/github.com/go-playground/log?status.svg)](https://godoc.org/github.com/go-playground/log)
77
![License](https://img.shields.io/dub/l/vibe-d.svg)
88
[![Gitter](https://badges.gitter.im/go-playground/log.svg)](https://gitter.im/go-playground/log?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
99

10-
Log is a simple,highly configurable, Structured Logging that is a near drop in replacement for the std library log
10+
Log is a simple, highly configurable, Structured Logging library
1111

1212
Why another logging library?
1313
----------------------------
14-
There's allot of great stuff out there, but also thought a log library could be made easier to use, more efficient by reusing objects and more performant using channels.
14+
There's allot of great stuff out there, but also thought a log library could be made more configurable using per handler log levels.
1515

1616
Features
1717
--------
1818
- [x] Logger is simple, only logic to create the log entry and send it off to the handlers and they take it from there.
19-
- [x] Sends the log entry to the handlers asynchronously, but waits for all to complete; meaning all your handlers can be dealing with the log entry at the same time, but log will wait until all have completed before moving on.
2019
- [x] Ability to specify which log levels get sent to each handler
21-
- [x] Built-in console, syslog, http, HipChat and email handlers
20+
- [x] Built-in console, syslog, http, HipChat, json and email handlers
2221
- [x] Handlers are simple to write + easy to register
2322
- [x] Logger is a singleton ( one of the few instances a singleton is desired ) so the root package registers which handlers are used and any libraries just follow suit.
23+
- [x] Convenient context helpers `GetContext` & `SetContext`
2424

2525
Installation
2626
-----------
2727

2828
Use go get
2929

3030
```go
31-
go get github.com/go-playground/log
31+
go get -u github.com/go-playground/log
3232
```
3333

34-
Replacing std log
35-
-----------------
36-
change import from
37-
```go
38-
import "log"
39-
```
40-
to
41-
```go
42-
import "github.com/go-playground/log"
43-
```
44-
4534
Usage
4635
------
4736
import the log package, setup at least one handler
4837
```go
4938
package main
5039

5140
import (
41+
"errors"
42+
5243
"github.com/go-playground/log"
5344
"github.com/go-playground/log/handlers/console"
5445
)
5546

5647
func main() {
57-
58-
cLog := console.New()
59-
60-
log.RegisterHandler(cLog, log.AllLevels...)
48+
cLog := console.New(true)
49+
log.AddHandler(cLog, log.AllLevels...)
6150

6251
// Trace
63-
defer log.Trace("trace").End()
52+
defer log.WithTrace().Info("time to run")
6453

6554
log.Debug("debug")
6655
log.Info("info")
@@ -71,8 +60,25 @@ func main() {
7160
log.Alert("alert")
7261
// log.Fatal("fatal") // this will call os.Exit(1)
7362

63+
err := errors.New("the is an error")
7464
// logging with fields can be used with any of the above
75-
log.WithFields(log.F("key", "value")).Info("test info")
65+
log.WithError(err).WithFields(log.F("key", "value")).Info("test info")
66+
67+
// predefined global fields
68+
log.WithDefaultFields(log.Fields{
69+
{"program", "test"},
70+
{"version", "0.1.3"},
71+
}...)
72+
73+
log.WithField("key", "value").Info("testing default fields")
74+
75+
// or request scoped default fields
76+
logger := log.WithFields(
77+
log.F("request", "req"),
78+
log.F("scoped", "sco"),
79+
)
80+
81+
logger.WithField("key", "value").Info("test")
7682
}
7783
```
7884

@@ -90,61 +96,40 @@ import (
9096
// CustomHandler is your custom handler
9197
type CustomHandler struct {
9298
// whatever properties you need
93-
buffer uint // channel buffer
9499
}
95100

96-
// Run starts the logger consuming on the returned channed
97-
func (c *CustomHandler) Run() chan<- *log.Entry {
98-
99-
// in a big high traffic app, set a higher buffer
100-
ch := make(chan *log.Entry, c.buffer)
101-
102-
// can run as many consumers on the channel as you want,
103-
// depending on the buffer size or your needs
104-
go func(entries <-chan *log.Entry) {
105-
106-
// below prints to os.Stderr but could marshal to JSON
107-
// and send to central logging server
108-
// ---------
109-
// |----------> | console |
110-
// | ---------
111-
// i.e. ----------------- ----------------- Unmarshal ------------- --------
112-
// | app log handler | -- json --> | central log app | -- to -> | log handler | --> | syslog |
113-
// ----------------- ----------------- Entry ------------- --------
114-
// | ---------
115-
// |----------> | DataDog |
116-
// ---------
117-
var e *log.Entry
118-
b := new(bytes.Buffer)
119-
120-
for e = range entries {
121-
122-
b.Reset()
123-
b.WriteString(e.Message)
124-
125-
for _, f := range e.Fields {
126-
fmt.Fprintf(b, " %s=%v", f.Key, f.Value)
127-
}
128-
129-
fmt.Println(b.String())
130-
e.Consumed() // done writing the entry
131-
}
132-
133-
}(ch)
134-
135-
return ch
101+
// Log accepts log entries to be processed
102+
func (c *CustomHandler) Log(e log.Entry) {
103+
104+
// below prints to os.Stderr but could marshal to JSON
105+
// and send to central logging server
106+
// ---------
107+
// |----------> | console |
108+
// | ---------
109+
// i.e. ----------------- ----------------- Unmarshal ------------- --------
110+
// | app log handler | -- json --> | central log app | -- to -> | log handler | --> | syslog |
111+
// ----------------- ----------------- Entry ------------- --------
112+
// | ---------
113+
// |----------> | DataDog |
114+
// ---------
115+
b := new(bytes.Buffer)
116+
b.Reset()
117+
b.WriteString(e.Message)
118+
119+
for _, f := range e.Fields {
120+
fmt.Fprintf(b, " %s=%v", f.Key, f.Value)
121+
}
122+
fmt.Println(b.String())
136123
}
137124

138125
func main() {
139126

140-
cLog := &CustomHandler{
141-
buffer: 0,
142-
}
127+
cLog := new(CustomHandler)
143128

144-
log.RegisterHandler(cLog, log.AllLevels...)
129+
log.AddHandler(cLog, log.AllLevels...)
145130

146131
// Trace
147-
defer log.Trace("trace").End()
132+
defer log.WithTrace().Info("took this long")
148133

149134
log.Debug("debug")
150135
log.Info("info")
@@ -156,7 +141,7 @@ func main() {
156141
// log.Fatal("fatal") // this will call os.Exit(1)
157142

158143
// logging with fields can be used with any of the above
159-
log.WithFields(log.F("key", "value")).Info("test info")
144+
log.WithField("key", "value").Info("test info")
160145
}
161146
```
162147

@@ -165,8 +150,6 @@ Log Level Definitions
165150

166151
**DebugLevel** - Info useful to developers for debugging the application, not useful during operations.
167152

168-
**TraceLevel** - Info useful to developers for debugging the application and reporting on possible bottlenecks.
169-
170153
**InfoLevel** - Normal operational messages - may be harvested for reporting, measuring throughput, etc. - no action required.
171154

172155
**NoticeLevel** - Normal but significant condition. Events that are unusual but not error conditions - might be summarized in an email to developers or admins to spot potential problems - no immediate action required.
@@ -185,13 +168,14 @@ Handlers
185168
-------------
186169
Pull requests for new handlers are welcome, please provide test coverage is all I ask.
187170

188-
| Handler | Description | Docs |
189-
| ------- | ---- | ----------- |
190-
| console | Allows for log messages to be sent to a any writer, default os.Stderr | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/console?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/console) |
191-
| syslog | Allows for log messages to be sent via syslog, includes TLS support. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/syslog?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/syslog) |
192-
| http | Allows for log messages to be sent via http. Can use the HTTP handler as a base for creating other handlers requiring http transmission. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/http?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/http) |
193-
| email | Allows for log messages to be sent via email. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/email?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/email) |
194-
| hipchat | Allows for log messages to be sent to a hipchat room. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/http/hipchat?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/http/hipchat) |
171+
| Handler | Description | Docs |
172+
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
173+
| console | Allows for log messages to be sent to a any writer, default os.Stderr | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/console?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/console) |
174+
| syslog | Allows for log messages to be sent via syslog, includes TLS support. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/syslog?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/syslog) |
175+
| http | Allows for log messages to be sent via http. Can use the HTTP handler as a base for creating other handlers requiring http transmission. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/http?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/http) |
176+
| email | Allows for log messages to be sent via email. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/email?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/email) |
177+
| hipchat | Allows for log messages to be sent to a hipchat room. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/http/hipchat?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/http/hipchat) |
178+
| json | Allows for log messages to be sent to any wrtier in json format. | [![GoDoc](https://godoc.org/github.com/go-playground/log/handlers/json?status.svg)](https://godoc.org/github.com/go-playground/log/handlers/json) |
195179

196180
Package Versioning
197181
----------
@@ -204,21 +188,20 @@ things for you the community.
204188

205189
Benchmarks
206190
----------
207-
###### Run on i5-7600 16 GB DDR4-2400 using Go version go1.8 linux/amd64
191+
###### Run on Macbook Pro 15-inch 2017 using go version go1.9.4 darwin/amd64
208192
NOTE: only putting benchmarks at others request, by no means does the number of allocations
209193
make one log library better than another!
210194
```go
211195
go test --bench=. -benchmem=true
212-
BenchmarkLogConsoleTenFieldsParallel-4 1000000 1294 ns/op 1065 B/op 32 allocs/op
213-
BenchmarkLogConsoleSimpleParallel-4 3000000 549 ns/op 104 B/op 5 allocs/op
214-
BenchmarkLogrusText10Fields-4 500000 2079 ns/op 2179 B/op 39 allocs/op
215-
BenchmarkLogrusTextSimple-4 3000000 402 ns/op 312 B/op 14 allocs/op
216-
BenchmarkLog1510Fields-4 200000 10915 ns/op 4362 B/op 91 allocs/op
217-
BenchmarkLog15Simple-4 1000000 1292 ns/op 320 B/op 9 allocs/op
196+
goos: darwin
197+
goarch: amd64
198+
pkg: github.com/go-playground/log/benchmarks
199+
BenchmarkLogConsoleTenFieldsParallel-8 2000000 946 ns/op 1376 B/op 16 allocs/op
200+
BenchmarkLogConsoleSimpleParallel-8 5000000 296 ns/op 200 B/op 4 allocs/op
218201
```
219202

220203
Special Thanks
221204
--------------
222205
Special thanks to the following libraries that inspired
223206
* [logrus](https://github.com/Sirupsen/logrus) - Structured, pluggable logging for Go.
224-
* [apex log](https://github.com/apex/log) - Structured logging package for Go.
207+
* [apex log](https://github.com/apex/log) - Structured logging package for Go.

‎_examples/basic/main.go‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
package main
22

33
import (
4+
"errors"
5+
46
"github.com/go-playground/log"
57
"github.com/go-playground/log/handlers/console"
68
)
79

810
func main() {
9-
10-
cLog := console.New()
11-
12-
log.RegisterHandler(cLog, log.AllLevels...)
11+
cLog := console.New(true)
12+
log.AddHandler(cLog, log.AllLevels...)
1313

1414
// Trace
15-
defer log.Trace("trace").End()
15+
defer log.WithTrace().Info("time to run")
1616

1717
log.Debug("debug")
1818
log.Info("info")
@@ -23,6 +23,23 @@ func main() {
2323
log.Alert("alert")
2424
// log.Fatal("fatal") // this will call os.Exit(1)
2525

26+
err := errors.New("the is an error")
2627
// logging with fields can be used with any of the above
27-
log.WithFields(log.F("key", "value")).Info("test info")
28+
log.WithError(err).WithFields(log.F("key", "value")).Info("test info")
29+
30+
// predefined global fields
31+
log.WithDefaultFields(log.Fields{
32+
{"program", "test"},
33+
{"version", "0.1.3"},
34+
}...)
35+
36+
log.WithField("key", "value").Info("testing default fields")
37+
38+
// or request scoped default fields
39+
logger := log.WithFields(
40+
log.F("request", "req"),
41+
log.F("scoped", "sco"),
42+
)
43+
44+
logger.WithField("key", "value").Info("test")
2845
}

0 commit comments

Comments
 (0)