-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Use Go's templating to remove the drudgery from updating the benchmarks in the README.
- Loading branch information
1 parent
3e4a6c3
commit 1d90273
Showing
4 changed files
with
294 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| # :zap: zap [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] | ||
|
|
||
| Blazing fast, structured, leveled logging in Go. | ||
|
|
||
| ## Installation | ||
|
|
||
| `go get -u go.uber.org/zap` | ||
|
|
||
| ## Quick Start | ||
|
|
||
| In contexts where performance is nice, but not critical, use the | ||
| `SugaredLogger`. It's 4-10x faster than than other structured logging libraries | ||
| and includes both structured and `printf`-style APIs. | ||
|
|
||
| ```go | ||
| logger, _ := NewProduction() | ||
| sugar := logger.Sugar() | ||
| sugar.Infow("Failed to fetch URL.", | ||
| // Structured context as loosely-typed key-value pairs. | ||
| "url", url, | ||
| "attempt", retryNum, | ||
| "backoff", time.Second, | ||
| ) | ||
| sugar.Infof("Failed to fetch URL: %s", url) | ||
| ``` | ||
|
|
||
| When performance and type safety are critical, use the `Logger`. It's even faster than | ||
| the `SugaredLogger` and allocates far less, but it only supports structured logging. | ||
|
|
||
| ```go | ||
| logger, _ := NewProduction() | ||
| logger.Info("Failed to fetch URL.", | ||
| // Structured context as strongly-typed Field values. | ||
| zap.String("url", url), | ||
| zap.Int("attempt", tryNum), | ||
| zap.Duration("backoff", time.Second), | ||
| ) | ||
| ``` | ||
|
|
||
| ## Performance | ||
|
|
||
| For applications that log in the hot path, reflection-based serialization and | ||
| string formatting are prohibitively expensive — they're CPU-intensive and | ||
| make many small allocations. Put differently, using `encoding/json` and | ||
| `fmt.Fprintf` to log tons of `interface{}`s makes your application slow. | ||
|
|
||
| Zap takes a different approach. It includes a reflection-free, zero-allocation | ||
| JSON encoder, and the base `Logger` strives to avoid serialization overhead and | ||
| allocations wherever possible. By building the high-level `SugaredLogger` on | ||
| that foundation, zap lets users *choose* when they need to count every | ||
| allocation and when they'd prefer a more familiar, loosely-typed API. | ||
|
|
||
| As measured by its own [benchmarking suite][], not only is zap more performant | ||
| than comparable structured logging libraries — it's also faster than the | ||
| standard library. Like all benchmarks, take these with a grain of salt.<sup | ||
| id="anchor-versions">[1](#footnote-versions)</sup> | ||
|
|
||
| Log a message and 10 fields: | ||
|
|
||
| {{.BenchmarkAddingFields}} | ||
|
|
||
| Log a message with a logger that already has 10 fields of context: | ||
|
|
||
| {{.BenchmarkAccumulatedContext}} | ||
|
|
||
| Log a static string, without any context or `printf`-style templating: | ||
|
|
||
| {{.BenchmarkWithoutFields}} | ||
|
|
||
| ## Development Status: Release Candidate 2 | ||
| The current release is `v1.0.0-rc.2`. No further breaking changes are *planned* | ||
| unless wider use reveals critical bugs or usability issues, but users who need | ||
| absolute stability should wait for the 1.0.0 release. | ||
|
|
||
| <hr> | ||
| Released under the [MIT License](LICENSE.txt). | ||
|
|
||
| <sup id="footnote-versions">1</sup> In particular, keep in mind that we may be | ||
| benchmarking against slightly older versions of other libraries. Versions are | ||
| pinned in zap's [glide.lock][] file. [↩](#anchor-versions) | ||
|
|
||
| [doc-img]: https://godoc.org/go.uber.org/zap?status.svg | ||
| [doc]: https://godoc.org/go.uber.org/zap | ||
| [ci-img]: https://travis-ci.org/uber-go/zap.svg?branch=master | ||
| [ci]: https://travis-ci.org/uber-go/zap | ||
| [cov-img]: https://coveralls.io/repos/github/uber-go/zap/badge.svg?branch=master | ||
| [cov]: https://coveralls.io/github/uber-go/zap?branch=master | ||
| [benchmarking suite]: https://github.com/uber-go/zap/tree/master/benchmarks | ||
| [glide.lock]: https://github.com/uber-go/zap/blob/master/glide.lock |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,175 @@ | ||
| // Copyright (c) 2016 Uber Technologies, Inc. | ||
| // | ||
| // 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. | ||
|
|
||
| package main | ||
|
|
||
| import ( | ||
| "flag" | ||
| "fmt" | ||
| "io/ioutil" | ||
| "log" | ||
| "os" | ||
| "os/exec" | ||
| "strings" | ||
| "text/template" | ||
| ) | ||
|
|
||
| var ( | ||
| libraryNames = []string{ | ||
| "Zap", | ||
| "Zap.Sugar", | ||
| "stdlib.Println", | ||
| "sirupsen/logrus", | ||
| "go-kit/kit/log", | ||
| "inconshreveable/log15", | ||
| "apex/log", | ||
| "go.pedge.io/lion", | ||
| } | ||
| libraryNameToMarkdownName = map[string]string{ | ||
| "Zap": ":zap: zap", | ||
| "Zap.Sugar": ":zap: zap (sugared)", | ||
| "stdlib.Println": "standard library", | ||
| "sirupsen/logrus": "logrus", | ||
| "go-kit/kit/log": "go-kit", | ||
| "inconshreveable/log15": "log15", | ||
| "apex/log": "apex/log", | ||
| "go.pedge.io/lion": "lion", | ||
| } | ||
| ) | ||
|
|
||
| func main() { | ||
| flag.Parse() | ||
| if err := do(); err != nil { | ||
| log.Fatal(err) | ||
| } | ||
| } | ||
|
|
||
| func do() error { | ||
| tmplData, err := getTmplData() | ||
| if err != nil { | ||
| return err | ||
| } | ||
| data, err := ioutil.ReadAll(os.Stdin) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| t, err := template.New("tmpl").Parse(string(data)) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| if err := t.Execute(os.Stdout, tmplData); err != nil { | ||
| return err | ||
| } | ||
| return nil | ||
| } | ||
|
|
||
| type tmplData struct { | ||
| BenchmarkAddingFields string | ||
| BenchmarkAccumulatedContext string | ||
| BenchmarkWithoutFields string | ||
| } | ||
|
|
||
| func getTmplData() (*tmplData, error) { | ||
| tmplData := &tmplData{} | ||
| rows, err := getBenchmarkRows("BenchmarkAddingFields") | ||
| if err != nil { | ||
| return nil, err | ||
| } | ||
| tmplData.BenchmarkAddingFields = rows | ||
| rows, err = getBenchmarkRows("BenchmarkAccumulatedContext") | ||
| if err != nil { | ||
| return nil, err | ||
| } | ||
| tmplData.BenchmarkAccumulatedContext = rows | ||
| rows, err = getBenchmarkRows("BenchmarkWithoutFields") | ||
| if err != nil { | ||
| return nil, err | ||
| } | ||
| tmplData.BenchmarkWithoutFields = rows | ||
| return tmplData, nil | ||
| } | ||
|
|
||
| func getBenchmarkRows(benchmarkName string) (string, error) { | ||
| benchmarkOutput, err := getBenchmarkOutput(benchmarkName) | ||
| if err != nil { | ||
| return "", err | ||
| } | ||
| rows := []string{ | ||
| "| Library | Time | Bytes Allocated | Objects Allocated |", | ||
| "| :--- | :---: | :---: | :---: |", | ||
| } | ||
| for _, libraryName := range libraryNames { | ||
| row, err := getBenchmarkRow(benchmarkOutput, benchmarkName, libraryName) | ||
| if err != nil { | ||
| return "", err | ||
| } | ||
| if row == "" { | ||
| continue | ||
| } | ||
| rows = append(rows, row) | ||
| } | ||
| return strings.Join(rows, "\n"), nil | ||
| } | ||
|
|
||
| func getBenchmarkRow(input []string, benchmarkName string, libraryName string) (string, error) { | ||
| line, err := findUniqueSubstring(input, fmt.Sprintf("%s/%s-", benchmarkName, libraryName)) | ||
| if err != nil { | ||
| return "", err | ||
| } | ||
| if line == "" { | ||
| return "", nil | ||
| } | ||
| split := strings.Split(line, "\t") | ||
| if len(split) < 5 { | ||
| return "", fmt.Errorf("unknown benchmark line: %s", line) | ||
| } | ||
| return fmt.Sprintf( | ||
| "| %s | %s | %s | %s |", | ||
| libraryNameToMarkdownName[libraryName], | ||
| strings.TrimSpace(split[2]), | ||
| strings.TrimSpace(split[3]), | ||
| strings.TrimSpace(split[4]), | ||
| ), nil | ||
| } | ||
|
|
||
| func findUniqueSubstring(input []string, substring string) (string, error) { | ||
| var output string | ||
| for _, line := range input { | ||
| if strings.Contains(line, substring) { | ||
| if output != "" { | ||
| return "", fmt.Errorf("input has duplicate substring %s", substring) | ||
| } | ||
| output = line | ||
| } | ||
| } | ||
| return output, nil | ||
| } | ||
|
|
||
| func getBenchmarkOutput(benchmarkName string) ([]string, error) { | ||
| return getOutput("go", "test", fmt.Sprintf("-bench=%s", benchmarkName), "-benchmem", "./benchmarks") | ||
| } | ||
|
|
||
| func getOutput(name string, arg ...string) ([]string, error) { | ||
| output, err := exec.Command(name, arg...).CombinedOutput() | ||
| if err != nil { | ||
| return nil, fmt.Errorf("error running %s %s: %v\n%s", name, strings.Join(arg, " "), err, string(output)) | ||
| } | ||
| return strings.Split(string(output), "\n"), nil | ||
| } |