github.com/hellobchain/third_party@v0.0.0-20230331131523-deb0478a2e52/go-kit/kit/log/README.md (about)

     1  # package log
     2  
     3  `package log` provides a minimal interface for structured logging in services.
     4  It may be wrapped to encode conventions, enforce type-safety, provide leveled
     5  logging, and so on. It can be used for both typical application log events,
     6  and log-structured data streams.
     7  
     8  ## Structured logging
     9  
    10  Structured logging is, basically, conceding to the reality that logs are
    11  _data_, and warrant some level of schematic rigor. Using a stricter,
    12  key/value-oriented message format for our logs, containing contextual and
    13  semantic information, makes it much easier to get insight into the
    14  operational activity of the systems we build. Consequently, `package log` is
    15  of the strong belief that "[the benefits of structured logging outweigh the
    16  minimal effort involved](https://www.thoughtworks.com/radar/techniques/structured-logging)".
    17  
    18  Migrating from unstructured to structured logging is probably a lot easier
    19  than you'd expect.
    20  
    21  ```go
    22  // Unstructured
    23  log.Printf("HTTP server listening on %s", addr)
    24  
    25  // Structured
    26  logger.Log("transport", "HTTP", "addr", addr, "msg", "listening")
    27  ```
    28  
    29  ## Usage
    30  
    31  ### Typical application logging
    32  
    33  ```go
    34  w := log.NewSyncWriter(os.Stderr)
    35  logger := log.NewLogfmtLogger(w)
    36  logger.Log("question", "what is the meaning of life?", "answer", 42)
    37  
    38  // Output:
    39  // question="what is the meaning of life?" answer=42
    40  ```
    41  
    42  ### Contextual Loggers
    43  
    44  ```go
    45  func main() {
    46  	var logger log.Logger
    47  	logger = log.NewLogfmtLogger(log.NewSyncWriter(os.Stderr))
    48  	logger = log.With(logger, "instance_id", 123)
    49  
    50  	logger.Log("msg", "starting")
    51  	NewWorker(log.With(logger, "component", "worker")).Run()
    52  	NewSlacker(log.With(logger, "component", "slacker")).Run()
    53  }
    54  
    55  // Output:
    56  // instance_id=123 msg=starting
    57  // instance_id=123 component=worker msg=running
    58  // instance_id=123 component=slacker msg=running
    59  ```
    60  
    61  ### Interact with stdlib logger
    62  
    63  Redirect stdlib logger to Go kit logger.
    64  
    65  ```go
    66  import (
    67  	"os"
    68  	stdlog "log"
    69  	kitlog "github.com/go-kit/kit/log"
    70  )
    71  
    72  func main() {
    73  	logger := kitlog.NewJSONLogger(kitlog.NewSyncWriter(os.Stdout))
    74  	stdlog.SetOutput(kitlog.NewStdlibAdapter(logger))
    75  	stdlog.Print("I sure like pie")
    76  }
    77  
    78  // Output:
    79  // {"msg":"I sure like pie","ts":"2016/01/01 12:34:56"}
    80  ```
    81  
    82  Or, if, for legacy reasons, you need to pipe all of your logging through the
    83  stdlib log package, you can redirect Go kit logger to the stdlib logger.
    84  
    85  ```go
    86  logger := kitlog.NewLogfmtLogger(kitlog.StdlibWriter{})
    87  logger.Log("legacy", true, "msg", "at least it's something")
    88  
    89  // Output:
    90  // 2016/01/01 12:34:56 legacy=true msg="at least it's something"
    91  ```
    92  
    93  ### Timestamps and callers
    94  
    95  ```go
    96  var logger log.Logger
    97  logger = log.NewLogfmtLogger(log.NewSyncWriter(os.Stderr))
    98  logger = log.With(logger, "ts", log.DefaultTimestampUTC, "caller", log.DefaultCaller)
    99  
   100  logger.Log("msg", "hello")
   101  
   102  // Output:
   103  // ts=2016-01-01T12:34:56Z caller=main.go:15 msg=hello
   104  ```
   105  
   106  ## Supported output formats
   107  
   108  - [Logfmt](https://brandur.org/logfmt) ([see also](https://blog.codeship.com/logfmt-a-log-format-thats-easy-to-read-and-write))
   109  - JSON
   110  
   111  ## Enhancements
   112  
   113  `package log` is centered on the one-method Logger interface.
   114  
   115  ```go
   116  type Logger interface {
   117  	Log(keyvals ...interface{}) error
   118  }
   119  ```
   120  
   121  This interface, and its supporting code like is the product of much iteration
   122  and evaluation. For more details on the evolution of the Logger interface,
   123  see [The Hunt for a Logger Interface](http://go-talks.appspot.com/github.com/ChrisHines/talks/structured-logging/structured-logging.slide#1),
   124  a talk by [Chris Hines](https://github.com/ChrisHines).
   125  Also, please see
   126  [#63](https://github.com/go-kit/kit/issues/63),
   127  [#76](https://github.com/go-kit/kit/pull/76),
   128  [#131](https://github.com/go-kit/kit/issues/131),
   129  [#157](https://github.com/go-kit/kit/pull/157),
   130  [#164](https://github.com/go-kit/kit/issues/164), and
   131  [#252](https://github.com/go-kit/kit/pull/252)
   132  to review historical conversations about package log and the Logger interface.
   133  
   134  Value-add packages and suggestions,
   135  like improvements to [the leveled logger](https://godoc.org/github.com/go-kit/kit/log/level),
   136  are of course welcome. Good proposals should
   137  
   138  - Be composable with [contextual loggers](https://godoc.org/github.com/go-kit/kit/log#With),
   139  - Not break the behavior of [log.Caller](https://godoc.org/github.com/go-kit/kit/log#Caller) in any wrapped contextual loggers, and
   140  - Be friendly to packages that accept only an unadorned log.Logger.
   141  
   142  ## Benchmarks & comparisons
   143  
   144  There are a few Go logging benchmarks and comparisons that include Go kit's package log.
   145  
   146  - [imkira/go-loggers-bench](https://github.com/imkira/go-loggers-bench) includes kit/log
   147  - [uber-common/zap](https://github.com/uber-common/zap), a zero-alloc logging library, includes a comparison with kit/log