From e1be995274d70c923c8a8a8b9dce7bdbe417ed39 Mon Sep 17 00:00:00 2001 From: Olivier Poitrey Date: Sat, 20 May 2017 02:03:07 -0700 Subject: [PATCH] Refactor README --- README.md | 118 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 62 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index b43dbd9..ff2f25d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,14 @@ [![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 simpler API and a smaller code base. +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](#performance). 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 pionieered this approach. Zerolog is taking this concept to the next level with simpler to use API and even better performance. + +To keep the code base and the API simple, zerolog focues on JSON logging only. + ## Features @@ -12,61 +19,6 @@ The zerolog package provides a fast and simple logger dedicated to JSON output. * `context.Context` integration * `net/http` helpers -## Performance - -All operations are allocation free (those numbers *include* JSON encoding): - -``` -BenchmarkLogEmpty-8 50000000 19.8 ns/op 0 B/op 0 allocs/op -BenchmarkDisabled-8 100000000 4.73 ns/op 0 B/op 0 allocs/op -BenchmarkInfo-8 10000000 85.1 ns/op 0 B/op 0 allocs/op -BenchmarkContextFields-8 10000000 81.9 ns/op 0 B/op 0 allocs/op -BenchmarkLogFields-8 5000000 247 ns/op 0 B/op 0 allocs/op -``` - -Using Uber's zap [comparison benchmark](https://github.com/uber-go/zap#performance): - -Log a message and 10 fields: - -| Library | Time | Bytes Allocated | Objects Allocated | -| :--- | :---: | :---: | :---: | -| zerolog | 787 ns/op | 80 B/op | 6 allocs/op | -| :zap: zap | 848 ns/op | 704 B/op | 2 allocs/op | -| :zap: zap (sugared) | 1363 ns/op | 1610 B/op | 20 allocs/op | -| go-kit | 3614 ns/op | 2895 B/op | 66 allocs/op | -| lion | 5392 ns/op | 5807 B/op | 63 allocs/op | -| logrus | 5661 ns/op | 6092 B/op | 78 allocs/op | -| apex/log | 15332 ns/op | 3832 B/op | 65 allocs/op | -| log15 | 20657 ns/op | 5632 B/op | 93 allocs/op | - -Log a message with a logger that already has 10 fields of context: - -| Library | Time | Bytes Allocated | Objects Allocated | -| :--- | :---: | :---: | :---: | -| zerolog | 80 ns/op | 0 B/op | 0 allocs/op | -| :zap: zap | 283 ns/op | 0 B/op | 0 allocs/op | -| :zap: zap (sugared) | 337 ns/op | 80 B/op | 2 allocs/op | -| lion | 2702 ns/op | 4074 B/op | 38 allocs/op | -| go-kit | 3378 ns/op | 3046 B/op | 52 allocs/op | -| logrus | 4309 ns/op | 4564 B/op | 63 allocs/op | -| apex/log | 13456 ns/op | 2898 B/op | 51 allocs/op | -| log15 | 14179 ns/op | 2642 B/op | 44 allocs/op | - -Log a static string, without any context or `printf`-style templating: - -| Library | Time | Bytes Allocated | Objects Allocated | -| :--- | :---: | :---: | :---: | -| zerolog | 76.2 ns/op | 0 B/op | 0 allocs/op | -| :zap: zap | 236 ns/op | 0 B/op | 0 allocs/op | -| standard library | 453 ns/op | 80 B/op | 2 allocs/op | -| :zap: zap (sugared) | 337 ns/op | 80 B/op | 2 allocs/op | -| go-kit | 508 ns/op | 656 B/op | 13 allocs/op | -| lion | 771 ns/op | 1224 B/op | 10 allocs/op | -| 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 | - - ## Usage ```go @@ -276,3 +228,57 @@ Some settings can be changed and will by applied to all loggers: * `Dict`: Adds a sub-key/value as a field of the event. * `Interface`: Uses reflection to marshal the type. +## Performance + +All operations are allocation free (those numbers *include* JSON encoding): + +``` +BenchmarkLogEmpty-8 50000000 19.8 ns/op 0 B/op 0 allocs/op +BenchmarkDisabled-8 100000000 4.73 ns/op 0 B/op 0 allocs/op +BenchmarkInfo-8 10000000 85.1 ns/op 0 B/op 0 allocs/op +BenchmarkContextFields-8 10000000 81.9 ns/op 0 B/op 0 allocs/op +BenchmarkLogFields-8 5000000 247 ns/op 0 B/op 0 allocs/op +``` + +Using Uber's zap [comparison benchmark](https://github.com/uber-go/zap#performance): + +Log a message and 10 fields: + +| Library | Time | Bytes Allocated | Objects Allocated | +| :--- | :---: | :---: | :---: | +| zerolog | 787 ns/op | 80 B/op | 6 allocs/op | +| :zap: zap | 848 ns/op | 704 B/op | 2 allocs/op | +| :zap: zap (sugared) | 1363 ns/op | 1610 B/op | 20 allocs/op | +| go-kit | 3614 ns/op | 2895 B/op | 66 allocs/op | +| lion | 5392 ns/op | 5807 B/op | 63 allocs/op | +| logrus | 5661 ns/op | 6092 B/op | 78 allocs/op | +| apex/log | 15332 ns/op | 3832 B/op | 65 allocs/op | +| log15 | 20657 ns/op | 5632 B/op | 93 allocs/op | + +Log a message with a logger that already has 10 fields of context: + +| Library | Time | Bytes Allocated | Objects Allocated | +| :--- | :---: | :---: | :---: | +| zerolog | 80 ns/op | 0 B/op | 0 allocs/op | +| :zap: zap | 283 ns/op | 0 B/op | 0 allocs/op | +| :zap: zap (sugared) | 337 ns/op | 80 B/op | 2 allocs/op | +| lion | 2702 ns/op | 4074 B/op | 38 allocs/op | +| go-kit | 3378 ns/op | 3046 B/op | 52 allocs/op | +| logrus | 4309 ns/op | 4564 B/op | 63 allocs/op | +| apex/log | 13456 ns/op | 2898 B/op | 51 allocs/op | +| log15 | 14179 ns/op | 2642 B/op | 44 allocs/op | + +Log a static string, without any context or `printf`-style templating: + +| Library | Time | Bytes Allocated | Objects Allocated | +| :--- | :---: | :---: | :---: | +| zerolog | 76.2 ns/op | 0 B/op | 0 allocs/op | +| :zap: zap | 236 ns/op | 0 B/op | 0 allocs/op | +| standard library | 453 ns/op | 80 B/op | 2 allocs/op | +| :zap: zap (sugared) | 337 ns/op | 80 B/op | 2 allocs/op | +| go-kit | 508 ns/op | 656 B/op | 13 allocs/op | +| lion | 771 ns/op | 1224 B/op | 10 allocs/op | +| 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 | +