Update README with instruction about binary encoding

This commit is contained in:
Olivier Poitrey 2018-03-28 11:57:11 -07:00
parent ddfae1b613
commit 05eafee0eb
1 changed files with 18 additions and 5 deletions

View File

@ -4,11 +4,11 @@
The zerolog package provides a fast and simple logger dedicated to JSON output. 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. 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 (or CBOR) log events by avoiding allocations and reflection.
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. 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`. To keep the code base and the API simple, zerolog focuses on efficient structured logging only. Pretty logging on the console is made possible using the provided (but inefficient) `zerolog.ConsoleWriter`.
![](pretty.png) ![](pretty.png)
@ -26,14 +26,18 @@ Find out [who uses zerolog](https://github.com/rs/zerolog/wiki/Who-uses-zerolog)
* Contextual fields * Contextual fields
* `context.Context` integration * `context.Context` integration
* `net/http` helpers * `net/http` helpers
* JSON and CBOR encoding formats
* Pretty logging for development * Pretty logging for development
## Installation ## Installation
```go ```go
go get -u github.com/rs/zerolog/log go get -u github.com/rs/zerolog/log
``` ```
## Getting Started ## Getting Started
### Simple Logging Example ### Simple Logging Example
For simple logging, import the global logger package **github.com/rs/zerolog/log** For simple logging, import the global logger package **github.com/rs/zerolog/log**
```go ```go
package main package main
@ -138,6 +142,7 @@ $ ./logLevelExample -debug
``` ```
#### Logging Fatal Messages #### Logging Fatal Messages
```go ```go
package main package main
@ -168,6 +173,7 @@ func main() {
### Contextual Logging ### Contextual Logging
#### Fields can be added to log messages #### Fields can be added to log messages
```go ```go
log.Info(). log.Info().
Str("foo", "bar"). Str("foo", "bar").
@ -422,6 +428,14 @@ Some settings can be changed and will by applied to all loggers:
* `Dict`: Adds a sub-key/value as a field of the event. * `Dict`: Adds a sub-key/value as a field of the event.
* `Interface`: Uses reflection to marshal the type. * `Interface`: Uses reflection to marshal the type.
## Binary Encoding
In addition to the default JSON encoding, `zerolog` can produce binary logs using the [cbor](http://cbor.io) encoding. The choice of encoding can be decided at compile time using the build tag `binary_log` as follow:
```
go build -tags binary_log .
```
## Benchmarks ## Benchmarks
All operations are allocation free (those numbers *include* JSON encoding): All operations are allocation free (those numbers *include* JSON encoding):
@ -483,8 +497,7 @@ Log a static string, without any context or `printf`-style templating:
## Caveats ## Caveats
There is no fields deduplication out-of-the-box. Note that zerolog does de-duplication fields. Using the same key multiple times creates multiple keys in final JSON:
Using the same key multiple times creates new key in final JSON each time.
```go ```go
logger := zerolog.New(os.Stderr).With().Timestamp().Logger() logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
@ -494,4 +507,4 @@ logger.Info().
// Output: {"level":"info","time":1494567715,"time":1494567715,"message":"dup"} // Output: {"level":"info","time":1494567715,"time":1494567715,"message":"dup"}
``` ```
However, its not a big deal though as JSON accepts dup keys, the last one prevails. However, its not a big deal as JSON accepts dup keys; the last one prevails.