Takahiro Suzuki | d7bf820 | 2020-12-17 20:21:59 +0900 | [diff] [blame] | 1 | // Copyright (c) 2016 Uber Technologies, Inc. |
| 2 | // |
| 3 | // Permission is hereby granted, free of charge, to any person obtaining a copy |
| 4 | // of this software and associated documentation files (the "Software"), to deal |
| 5 | // in the Software without restriction, including without limitation the rights |
| 6 | // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 7 | // copies of the Software, and to permit persons to whom the Software is |
| 8 | // furnished to do so, subject to the following conditions: |
| 9 | // |
| 10 | // The above copyright notice and this permission notice shall be included in |
| 11 | // all copies or substantial portions of the Software. |
| 12 | // |
| 13 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 14 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 15 | // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 16 | // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 17 | // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 18 | // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
| 19 | // THE SOFTWARE. |
| 20 | |
| 21 | // Package zap provides fast, structured, leveled logging. |
| 22 | // |
| 23 | // For applications that log in the hot path, reflection-based serialization |
| 24 | // and string formatting are prohibitively expensive - they're CPU-intensive |
| 25 | // and make many small allocations. Put differently, using json.Marshal and |
| 26 | // fmt.Fprintf to log tons of interface{} makes your application slow. |
| 27 | // |
| 28 | // Zap takes a different approach. It includes a reflection-free, |
| 29 | // zero-allocation JSON encoder, and the base Logger strives to avoid |
| 30 | // serialization overhead and allocations wherever possible. By building the |
| 31 | // high-level SugaredLogger on that foundation, zap lets users choose when |
| 32 | // they need to count every allocation and when they'd prefer a more familiar, |
| 33 | // loosely typed API. |
| 34 | // |
| 35 | // Choosing a Logger |
| 36 | // |
| 37 | // In contexts where performance is nice, but not critical, use the |
| 38 | // SugaredLogger. It's 4-10x faster than other structured logging packages and |
| 39 | // supports both structured and printf-style logging. Like log15 and go-kit, |
| 40 | // the SugaredLogger's structured logging APIs are loosely typed and accept a |
| 41 | // variadic number of key-value pairs. (For more advanced use cases, they also |
| 42 | // accept strongly typed fields - see the SugaredLogger.With documentation for |
| 43 | // details.) |
| 44 | // sugar := zap.NewExample().Sugar() |
| 45 | // defer sugar.Sync() |
| 46 | // sugar.Infow("failed to fetch URL", |
| 47 | // "url", "http://example.com", |
| 48 | // "attempt", 3, |
| 49 | // "backoff", time.Second, |
| 50 | // ) |
| 51 | // sugar.Infof("failed to fetch URL: %s", "http://example.com") |
| 52 | // |
| 53 | // By default, loggers are unbuffered. However, since zap's low-level APIs |
| 54 | // allow buffering, calling Sync before letting your process exit is a good |
| 55 | // habit. |
| 56 | // |
| 57 | // In the rare contexts where every microsecond and every allocation matter, |
| 58 | // use the Logger. It's even faster than the SugaredLogger and allocates far |
| 59 | // less, but it only supports strongly-typed, structured logging. |
| 60 | // logger := zap.NewExample() |
| 61 | // defer logger.Sync() |
| 62 | // logger.Info("failed to fetch URL", |
| 63 | // zap.String("url", "http://example.com"), |
| 64 | // zap.Int("attempt", 3), |
| 65 | // zap.Duration("backoff", time.Second), |
| 66 | // ) |
| 67 | // |
| 68 | // Choosing between the Logger and SugaredLogger doesn't need to be an |
| 69 | // application-wide decision: converting between the two is simple and |
| 70 | // inexpensive. |
| 71 | // logger := zap.NewExample() |
| 72 | // defer logger.Sync() |
| 73 | // sugar := logger.Sugar() |
| 74 | // plain := sugar.Desugar() |
| 75 | // |
| 76 | // Configuring Zap |
| 77 | // |
| 78 | // The simplest way to build a Logger is to use zap's opinionated presets: |
| 79 | // NewExample, NewProduction, and NewDevelopment. These presets build a logger |
| 80 | // with a single function call: |
| 81 | // logger, err := zap.NewProduction() |
| 82 | // if err != nil { |
| 83 | // log.Fatalf("can't initialize zap logger: %v", err) |
| 84 | // } |
| 85 | // defer logger.Sync() |
| 86 | // |
| 87 | // Presets are fine for small projects, but larger projects and organizations |
| 88 | // naturally require a bit more customization. For most users, zap's Config |
| 89 | // struct strikes the right balance between flexibility and convenience. See |
| 90 | // the package-level BasicConfiguration example for sample code. |
| 91 | // |
| 92 | // More unusual configurations (splitting output between files, sending logs |
| 93 | // to a message queue, etc.) are possible, but require direct use of |
| 94 | // go.uber.org/zap/zapcore. See the package-level AdvancedConfiguration |
| 95 | // example for sample code. |
| 96 | // |
| 97 | // Extending Zap |
| 98 | // |
| 99 | // The zap package itself is a relatively thin wrapper around the interfaces |
| 100 | // in go.uber.org/zap/zapcore. Extending zap to support a new encoding (e.g., |
| 101 | // BSON), a new log sink (e.g., Kafka), or something more exotic (perhaps an |
| 102 | // exception aggregation service, like Sentry or Rollbar) typically requires |
| 103 | // implementing the zapcore.Encoder, zapcore.WriteSyncer, or zapcore.Core |
| 104 | // interfaces. See the zapcore documentation for details. |
| 105 | // |
| 106 | // Similarly, package authors can use the high-performance Encoder and Core |
| 107 | // implementations in the zapcore package to build their own loggers. |
| 108 | // |
| 109 | // Frequently Asked Questions |
| 110 | // |
| 111 | // An FAQ covering everything from installation errors to design decisions is |
| 112 | // available at https://github.com/uber-go/zap/blob/master/FAQ.md. |
| 113 | package zap // import "go.uber.org/zap" |