Update README with instruction about binary encoding
This commit is contained in:
parent
ddfae1b613
commit
05eafee0eb
23
README.md
23
README.md
|
@ -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, it’s not a big deal though as JSON accepts dup keys, the last one prevails.
|
However, it’s not a big deal as JSON accepts dup keys; the last one prevails.
|
||||||
|
|
Loading…
Reference in New Issue