Updates to README.md to help with readability (#32)

* Added missed >m< in github.com
* Added backquotes to denote "code" where appropriate
* Cleanup based on feedback
* Added three examples from README
* Removed Output for 3 examples
* Updated Setting Global Log Level section w/ flags
* Removed unnecessary blank lines
* Moved flags from init into main
* Update log_example_test.go
* Cosmetic change based on Olivier's feedback
* Pushed back to original
* New Examples for Log package
* Removed extra spaces
* Reorganized file and added examples

README.md

@@ -6,7 +6,7 @@ The zerolog package provides a fast and simple logger dedicated to JSON output.
 
 Zerolog's API is designed to provide both a great developer experience and stunning [performance](#benchmarks). Its unique chaining API allows zerolog to write JSON log events by avoiding allocations and reflection.
 
-The uber's [zap](https://godoc.org/go.uber.org/zap) library pioneered this approach. Zerolog is taking this concept to the next level with simpler to use API and even better performance.
+Uber's [zap](https://godoc.org/go.uber.org/zap) library pioneered this approach. Zerolog is taking this concept to the next level with a simpler to use API and even better performance.
 
 To keep the code base and the API simple, zerolog focuses on JSON logging only. Pretty logging on the console is made possible using the provided (but inefficient) `zerolog.ConsoleWriter`.
 
@@ -24,43 +24,144 @@ To keep the code base and the API simple, zerolog focuses on JSON logging only.
 * `net/http` helpers
 * Pretty logging for development
 
-## Usage
+## Installation
+```go
+go get -u github.com/rs/zerolog/log
+```
+## Getting Started
+### Simple Logging Example
+For simple logging, import the global logger package **github.com/rs/zerolog/log**
+```go
+package main
+
+import (
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+)
+
+func main() {
+	// UNIX Time is faster and smaller than most timestamps
+	// If you set zerolog.TimeFieldFormat to an empty string,
+	// logs will write with UNIX time
+	zerolog.TimeFieldFormat = ""
+
+	log.Print("hello world")
+}
+
+// Output: {"time":1516134303,"level":"debug","message":"hello world"}
+```
+> Note: The default log level for `log.Print` is *debug*
+----
+### Leveled Logging
+
+#### Simple Leveled Logging Example
 
 ```go
-import "github.com/rs/zerolog/log"
+package main
+
+import (
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+)
+
+func main() {
+	zerolog.TimeFieldFormat = ""
+
+	log.Info().Msg("hello world")
+}
+
+// Output: {"time":1516134303,"level":"info","message":"hello world"}
 ```
 
-### A global logger can be use for simple logging
+**zerolog** allows for logging at the following levels (from highest to lowest):
+- panic (`zerolog.PanicLevel`, 5)
+- fatal (`zerolog.FatalLevel`, 4)
+- error (`zerolog.ErrorLevel`, 3)
+- warn (`zerolog.WarnLevel`, 2)
+- info (`zerolog.InfoLevel`, 1)
+- debug (`zerolog.DebugLevel`, 0)
 
+You can set the Global logging level to any of these options using the `SetGlobalLevel` function in the zerolog package, passing in one of the given constants above, e.g. `zerolog.InfoLevel` would be the "info" level.  Whichever level is chosen, all logs with a level greater than or equal to that level will be written. To turn off logging entirely, pass the `zerolog.Disabled` constant.
+
+#### Setting Global Log Level
+This example uses command-line flags to demonstrate various outputs depending on the chosen log level.
 ```go
-log.Print("hello world")
+package main
 
-// Output: {"level":"debug","time":1494567715,"message":"hello world"}
+import (
+	"flag"
+
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+)
+
+func main() {
+	zerolog.TimeFieldFormat = ""
+	debug := flag.Bool("debug", false, "sets log level to debug")
+
+	flag.Parse()
+
+	// Default level for this example is info, unless debug flag is present
+	zerolog.SetGlobalLevel(zerolog.InfoLevel)
+	if *debug {
+		zerolog.SetGlobalLevel(zerolog.DebugLevel)
+	}
+
+	log.Debug().Msg("This message appears only when log level set to Debug")
+	log.Info().Msg("This message appears when log level set to Debug or Info")
+
+	if e := log.Debug(); e.Enabled() {
+		// Compute log output only if enabled.
+		value := "bar"
+		e.Str("foo", value).Msg("some debug message")
+	}
+}
+```
+Info Output (no flag)
+```bash
+$ ./logLevelExample
+{"time":1516387492,"level":"info","message":"This message appears when log level set to Debug or Info"}
 ```
 
-
+Debug Output (debug flag set)
-```go
+```bash
-log.Info().Msg("hello world")
+$ ./logLevelExample -debug
-
+{"time":1516387573,"level":"debug","message":"This message appears only when log level set to Debug"}
-// Output: {"level":"info","time":1494567715,"message":"hello world"}
+{"time":1516387573,"level":"info","message":"This message appears when log level set to Debug or Info"}
+{"time":1516387573,"level":"debug","foo":"bar","message":"some debug message"}
 ```
 
-NOTE: To import the global logger, import the `log` subpackage `github.com/rs/zerolog/log`.
+#### Logging Fatal Messages
-
 ```go
-log.Fatal().
+package main
+
+import (
+	"errors"
+
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+)
+
+func main() {
+	err := errors.New("A repo man spends his life getting into tense situations")
+	service := "myservice"
+
+	zerolog.TimeFieldFormat = ""
+
+	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"}
+// Output: {"time":1516133263,"level":"fatal","error":"A repo man spends his life getting into tense situations","service":"myservice","message":"Cannot start myservice"}
-// Exit 1
+//         exit status 1
 ```
+> NOTE: Using `Msgf` generates one allocation even when the logger is disabled.
+----------------
+### Contextual Logging
 
-NOTE: Using `Msgf` generates one allocation even when the logger is disabled.
+#### Fields can be added to log messages
-
-### Fields can be added to log messages
-
 ```go
 log.Info().
     Str("foo", "bar").
@@ -91,22 +192,7 @@ sublogger.Info().Msg("hello world")
 // Output: {"level":"info","time":1494567715,"message":"hello world","component":"foo"}
 ```
 
-### Level logging
 
-```go
-zerolog.SetGlobalLevel(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,"message":"routed message"}
-```
 
 ### Pretty logging
 
@@ -375,4 +461,3 @@ Log a static string, without any context or `printf`-style templating:
 | logrus | 1244 ns/op | 1505 B/op | 27 allocs/op |
 | apex/log | 2751 ns/op | 584 B/op | 11 allocs/op |
 | log15 | 5181 ns/op | 1592 B/op | 26 allocs/op |
-

log/log_example_test.go

@@ -0,0 +1,141 @@
+package log_test
+
+import (
+	"errors"
+	"flag"
+	"os"
+	"time"
+
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+)
+
+// setup would normally be an init() function, however, there seems
+// to be something awry with the testing framework when we set the
+// global Logger from an init()
+func setup() {
+	// UNIX Time is faster and smaller than most timestamps
+	// If you set zerolog.TimeFieldFormat to an empty string,
+	// logs will write with UNIX time
+	zerolog.TimeFieldFormat = ""
+	// In order to always output a static time to stdout for these
+	// examples to pass, we need to override zerolog.TimestampFunc
+	// and log.Logger globals -- you would not normally need to do this
+	zerolog.TimestampFunc = func() time.Time {
+		return time.Date(2008, 1, 8, 17, 5, 05, 0, time.UTC)
+	}
+	log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()
+}
+
+// Simple logging example using the Print function in the log package
+// Note that both Print and Printf are at the debug log level by default
+func ExamplePrint() {
+	setup()
+
+	log.Print("hello world")
+	// Output: {"time":1199811905,"level":"debug","message":"hello world"}
+}
+
+// Simple logging example using the Printf function in the log package
+func ExamplePrintf() {
+	setup()
+
+	log.Printf("hello %s", "world")
+	// Output: {"time":1199811905,"level":"debug","message":"hello world"}
+}
+
+// Example of a log with no particular "level"
+func ExampleLog() {
+	setup()
+	log.Log().Msg("hello world")
+
+	// Output: {"time":1199811905,"message":"hello world"}
+}
+
+// Example of a log at a particular "level" (in this case, "debug")
+func ExampleDebug() {
+	setup()
+	log.Debug().Msg("hello world")
+
+	// Output: {"time":1199811905,"level":"debug","message":"hello world"}
+}
+
+// Example of a log at a particular "level" (in this case, "info")
+func ExampleInfo() {
+	setup()
+	log.Info().Msg("hello world")
+
+	// Output: {"time":1199811905,"level":"info","message":"hello world"}
+}
+
+// Example of a log at a particular "level" (in this case, "warn")
+func ExampleWarn() {
+	setup()
+	log.Warn().Msg("hello world")
+
+	// Output: {"time":1199811905,"level":"warn","message":"hello world"}
+}
+
+// Example of a log at a particular "level" (in this case, "error")
+func ExampleError() {
+	setup()
+	log.Error().Msg("hello world")
+
+	// Output: {"time":1199811905,"level":"error","message":"hello world"}
+}
+
+// Example of a log at a particular "level" (in this case, "fatal")
+func ExampleFatal() {
+	setup()
+	err := errors.New("A repo man spends his life getting into tense situations")
+	service := "myservice"
+
+	log.Fatal().
+		Err(err).
+		Str("service", service).
+		Msgf("Cannot start %s", service)
+
+	// Outputs: {"time":1199811905,"level":"fatal","error":"A repo man spends his life getting into tense situations","service":"myservice","message":"Cannot start myservice"}
+}
+
+// TODO: Panic
+
+// This example uses command-line flags to demonstrate various outputs
+// depending on the chosen log level.
+func ExampleLevelFlag() {
+	setup()
+	debug := flag.Bool("debug", false, "sets log level to debug")
+
+	flag.Parse()
+
+	// Default level for this example is info, unless debug flag is present
+	zerolog.SetGlobalLevel(zerolog.InfoLevel)
+	if *debug {
+		zerolog.SetGlobalLevel(zerolog.DebugLevel)
+	}
+
+	log.Debug().Msg("This message appears only when log level set to Debug")
+	log.Info().Msg("This message appears when log level set to Debug or Info")
+
+	if e := log.Debug(); e.Enabled() {
+		// Compute log output only if enabled.
+		value := "bar"
+		e.Str("foo", value).Msg("some debug message")
+	}
+
+	// Output: {"time":1199811905,"level":"info","message":"This message appears when log level set to Debug or Info"}
+}
+
+// TODO: Output
+
+// TODO: With
+
+// TODO: Level
+
+// TODO: Sample
+
+// TODO: Hook
+
+// TODO: WithLevel
+
+// TODO: Ctx