Initial commit

openk8sai · May 13, 2017 · 7f302b0 · 7f302b0
commit 7f302b0
Show file tree

Hide file tree

Showing 15 changed files with 1,546 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,24 @@
+# Compiled Object files, Static and Dynamic libs (Shared Objects)
+*.o
+*.a
+*.so
+
+# Folders
+_obj
+_test
+
+# Architecture specific extensions/prefixes
+*.[568vq]
+[568vq].out
+
+*.cgo1.go
+*.cgo2.c
+_cgo_defun.c
+_cgo_gotypes.go
+_cgo_export.*
+
+_testmain.go
+
+*.exe
+*.test
+*.prof
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,10 @@
+language: go
+go:
+- 1.7
+- 1.8
+- tip
+matrix:
+  allow_failures:
+      - go: tip
+script:
+    go test -v -race -cpu=1,2,4 ./...
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Olivier Poitrey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,165 @@
+# Zero Allocation JSON Logger
+
+[![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/rs/zerolog) [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/rs/zerolog/master/LICENSE) [![Build Status](https://travis-ci.org/rs/zerolog.svg?branch=master)](https://travis-ci.org/rs/zerolog) [![Coverage](http://gocover.io/_badge/github.com/rs/zerolog)](http://gocover.io/github.com/rs/zerolog)
+
+The zerolog package provides a fast and simple logger dedicated to JSON output. It is inspired by uber's [zap](https://godoc.org/go.uber.org/zap) but with a mutch simpler to use API and smaller code base.
+
+## Features
+
+* Level logging
+* Sampling
+* Contextual fields
+
+## Benchmark
+
+All operations are allocation free:
+
+```
+BenchmarkLogEmpty-8            50000000      22 ns/op       0 B/op      0 allocs/op
+BenchmarkDisabled-8           100000000      10 ns/op       0 B/op      0 allocs/op
+BenchmarkInfo-8                10000000     210 ns/op       0 B/op      0 allocs/op
+BenchmarkContextFields-8       10000000     254 ns/op       0 B/op      0 allocs/op
+BenchmarkLogFields-8            5000000     377 ns/op       0 B/op      0 allocs/op
+```
+
+## Usage
+
+```go
+import "github.com/rs/zerolog/log"
+```
+
+### A global logger can be use for simple logging
+
+```go
+log.Info().Msg("hello world")
+
+// Output: {"level":"info","time":1494567715,"message":"hello world"}
+```
+
+NOTE: To import the global logger, import the `log` subpackage `github.com/rs/zerolog/log`.
+
+```go
+log.Fatal().
+    Err(err).
+    Str("service", service).
+    Msgf("Cannot start %s", service)
+
+// Output: {"level":"fatal","time":1494567715,"message":"Cannot start myservice","error":"some error","service":"myservice"}
+// Exit 1
+```
+
+NOTE: Using `Msgf` generates an allocation even when the logger is disabled.
+
+### Fields can be added to log messages
+
+```go
+log.Info().
+    Str("foo", "bar").
+    Int("n", 123).
+    Msg("hello world")
+
+// Output: {"level":"info","time":1494567715,"foo":"bar","n":123,"message":"hello world"}
+```
+
+### Create logger instance to manage different outputs
+
+```go
+logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
+
+logger.Info().Str("foo", "bar").Msg("hello world")
+
+// Output: {"level":"info","time":1494567715,"message":"hello world","foo":"bar"}
+```
+
+### Sub-loggers let you chain loggers with additional context
+
+```go
+sublogger := log.With().
+                 Str("component": "foo").
+                 Logger()
+sublogger.Info().Msg("hello world")
+
+// Output: {"level":"info","time":1494567715,"message":"hello world","component":"foo"}
+```
+
+### Level logging
+
+```go
+zerolog.GlobalLevel = zerolog.InfoLevel
+
+log.Debug().Msg("filtered out message")
+log.Info().Msg("routed message")
+
+if e := log.Debug(); e.Enabled() {
+    // Compute log output only if enabled.
+    value := compute()
+    e.Str("foo": value).Msg("some debug message")
+}
+
+// Output: {"level":"info","time":1494567715,"routed message"}
+```
+
+
+### Customize automatic field names
+
+```go
+zerolog.TimestampFieldName = "t"
+zerolog.LevelFieldName = "l"
+zerolog.MessageFieldName = "m"
+
+log.Info().Msg("hello world")
+
+// Output: {"l":"info","t":1494567715,"m":"hello world"}
+```
+
+### Log with no level nor message
+
+```go
+log.Log().Str("foo","bar").Msg("")
+
+// Output: {"time":1494567715,"foo":"bar"}
+```
+
+### Add contextual fields to the global logger
+
+```go
+log.Logger = log.With().Str("foo", "bar").Logger()
+```
+
+### Log Sampling
+
+```go
+sampled := log.Sample(10)
+sampled.Info().Msg("will be logged every 10 messages")
+```
+
+## Global Settings
+
+Some settings can be changed and will by applied to all loggers:
+
+* `log.Logger`: You can set this value to customize the global logger (the one used by package level methods).
+* `zerolog.GlobalLevel`: Can raise the mimimum level of all loggers. Set this to `zerolog.Disable` to disable logging altogether (quiet mode).
+* `zerolog.SamplingDisable`: If set to `true`, all sampled loggers will stop sampling and issue 100% of their log events.
+* `zerolog.TimestampFieldName`: Can be set to customize `Timestamp` field name.
+* `zerolog.LevelFieldName`: Can be set to customize level field name.
+* `zerolog.MessageFieldName`: Can be set to customize message field name.
+* `zerolog.ErrorFieldName`: Can be set to customize `Err` field name.
+* `zerolog.SampleFieldName`: Can be set to customize the field name added when sampling is enabled.
+* `zerolog.TimeFieldFormat`: Can be set to customize `Time` field value formatting.
+
+## Field Types
+
+### Standard Types
+
+* `Str`
+* `Bool`
+* `Int`, `Int8`, `Int16`, `Int32`, `Int64`
+* `Uint`, `Uint8`, `Uint16`, `Uint32`, `Uint64`
+* `Float32`, `Float64`
+
+### Advanced Fields
+
+* `Timestamp`: Insert UNIX timestamp field with `zerolog.TimestampFieldName` field name.
+* `Time`: Add a field with the time formated with the `zerolog.TimeFieldFormat`.
+* `Err`: Takes an `error` and render it as a string using the `zerolog.ErrorFieldName` field name.
+
diff --git a/benchmark_test.go b/benchmark_test.go
@@ -0,0 +1,72 @@
+package zerolog
+
+import (
+	"errors"
+	"io/ioutil"
+	"testing"
+)
+
+var (
+	errExample  = errors.New("fail")
+	fakeMessage = "Test logging, but use a somewhat realistic message length."
+)
+
+func BenchmarkLogEmpty(b *testing.B) {
+	logger := New(ioutil.Discard)
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			logger.Log().Msg("")
+		}
+	})
+}
+
+func BenchmarkDisabled(b *testing.B) {
+	logger := New(ioutil.Discard).Level(Disabled)
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			logger.Info().Msg(fakeMessage)
+		}
+	})
+}
+
+func BenchmarkInfo(b *testing.B) {
+	logger := New(ioutil.Discard)
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			logger.Info().Msg(fakeMessage)
+		}
+	})
+}
+
+func BenchmarkContextFields(b *testing.B) {
+	logger := New(ioutil.Discard).With().
+		Str("string", "four!").
+		Str("time", "now").     // XXX
+		Str("duration", "123"). //XXX
+		Str("another string", "done!").
+		Logger()
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			logger.Info().Msg(fakeMessage)
+		}
+	})
+}
+
+func BenchmarkLogFields(b *testing.B) {
+	logger := New(ioutil.Discard)
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			logger.Info().
+				Str("string", "four!").
+				Str("time", "now").     // XXX
+				Str("duration", "123"). //XXX
+				Str("another string", "done!").
+				Msg(fakeMessage)
+		}
+	})
+}
diff --git a/context.go b/context.go
@@ -0,0 +1,94 @@
+package zerolog
+
+import "time"
+
+// Context configures a new sub-logger with contextual fields.
+type Context struct {
+	l Logger
+}
+
+// Logger returns the logger with the context previously set.
+func (c Context) Logger() Logger {
+	return c.l
+}
+
+func (c Context) append(f field) Context {
+	return Context{
+		l: Logger{
+			parent:  c.l,
+			w:       c.l.w,
+			field:   f.compileJSON(),
+			level:   c.l.level,
+			sample:  c.l.sample,
+			counter: c.l.counter,
+		},
+	}
+}
+
+func (c Context) Str(key, val string) Context {
+	return c.append(fStr(key, val))
+}
+
+func (c Context) Err(err error) Context {
+	return c.append(fErr(err))
+}
+
+func (c Context) Bool(key string, b bool) Context {
+	return c.append(fBool(key, b))
+}
+
+func (c Context) Int(key string, i int) Context {
+	return c.append(fInt(key, i))
+}
+
+func (c Context) Int8(key string, i int8) Context {
+	return c.append(fInt8(key, i))
+}
+
+func (c Context) Int16(key string, i int16) Context {
+	return c.append(fInt16(key, i))
+}
+
+func (c Context) Int32(key string, i int32) Context {
+	return c.append(fInt32(key, i))
+}
+
+func (c Context) Int64(key string, i int64) Context {
+	return c.append(fInt64(key, i))
+}
+
+func (c Context) Uint(key string, i uint) Context {
+	return c.append(fUint(key, i))
+}
+
+func (c Context) Uint8(key string, i uint8) Context {
+	return c.append(fUint8(key, i))
+}
+
+func (c Context) Uint16(key string, i uint16) Context {
+	return c.append(fUint16(key, i))
+}
+
+func (c Context) Uint32(key string, i uint32) Context {
+	return c.append(fUint32(key, i))
+}
+
+func (c Context) Uint64(key string, i uint64) Context {
+	return c.append(fUint64(key, i))
+}
+
+func (c Context) Float32(key string, f float32) Context {
+	return c.append(fFloat32(key, f))
+}
+
+func (c Context) Float64(key string, f float64) Context {
+	return c.append(fFloat64(key, f))
+}
+
+func (c Context) Timestamp() Context {
+	return c.append(fTimestamp())
+}
+
+func (c Context) Time(key string, t time.Time) Context {
+	return c.append(fTime(key, t))
+}