vendor/github.com/hashicorp/go-hclog/README.md

   1 # go-hclog
   2
   3 [![Go Documentation](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)][godocs]
   4
   5 [godocs]: https://godoc.org/github.com/hashicorp/go-hclog
   6
   7 `go-hclog` is a package for Go that provides a simple key/value logging
   8 interface for use in development and production environments.
   9
  10 It provides logging levels that provide decreased output based upon the
  11 desired amount of output, unlike the standard library `log` package.
  12
  13 It does not provide `Printf` style logging, only key/value logging that is
  14 exposed as arguments to the logging functions for simplicity.
  15
  16 It provides a human readable output mode for use in development as well as
  17 JSON output mode for production.
  18
  19 ## Stability Note
  20
  21 While this library is fully open source and HashiCorp will be maintaining it
  22 (since we are and will be making extensive use of it), the API and output
  23 format is subject to minor changes as we fully bake and vet it in our projects.
  24 This notice will be removed once it's fully integrated into our major projects
  25 and no further changes are anticipated.
  26
  27 ## Installation and Docs
  28
  29 Install using `go get github.com/hashicorp/go-hclog`.
  30
  31 Full documentation is available at
  32 http://godoc.org/github.com/hashicorp/go-hclog
  33
  34 ## Usage
  35
  36 ### Use the global logger
  37
  38 ```go
  39 hclog.Default().Info("hello world")
  40 ```
  41
  42 ```text
  43 2017-07-05T16:15:55.167-0700 [INFO ] hello world
  44 ```
  45
  46 (Note timestamps are removed in future examples for brevity.)
  47
  48 ### Create a new logger
  49
  50 ```go
  51 appLogger := hclog.New(&hclog.LoggerOptions{
  52         Name:  "my-app",
  53         Level: hclog.LevelFromString("DEBUG"),
  54 })
  55 ```
  56
  57 ### Emit an Info level message with 2 key/value pairs
  58
  59 ```go
  60 input := "5.5"
  61 _, err := strconv.ParseInt(input, 10, 32)
  62 if err != nil {
  63         appLogger.Info("Invalid input for ParseInt", "input", input, "error", err)
  64 }
  65 ```
  66
  67 ```text
  68 ... [INFO ] my-app: Invalid input for ParseInt: input=5.5 error="strconv.ParseInt: parsing "5.5": invalid syntax"
  69 ```
  70
  71 ### Create a new Logger for a major subsystem
  72
  73 ```go
  74 subsystemLogger := appLogger.Named("transport")
  75 subsystemLogger.Info("we are transporting something")
  76 ```
  77
  78 ```text
  79 ... [INFO ] my-app.transport: we are transporting something
  80 ```
  81
  82 Notice that logs emitted by `subsystemLogger` contain `my-app.transport`,
  83 reflecting both the application and subsystem names.
  84
  85 ### Create a new Logger with fixed key/value pairs
  86
  87 Using `With()` will include a specific key-value pair in all messages emitted
  88 by that logger.
  89
  90 ```go
  91 requestID := "5fb446b6-6eba-821d-df1b-cd7501b6a363"
  92 requestLogger := subsystemLogger.With("request", requestID)
  93 requestLogger.Info("we are transporting a request")
  94 ```
  95
  96 ```text
  97 ... [INFO ] my-app.transport: we are transporting a request: request=5fb446b6-6eba-821d-df1b-cd7501b6a363
  98 ```
  99
 100 This allows sub Loggers to be context specific without having to thread that
 101 into all the callers.
 102
 103 ### Use this with code that uses the standard library logger
 104
 105 If you want to use the standard library's `log.Logger` interface you can wrap
 106 `hclog.Logger` by calling the `StandardLogger()` method. This allows you to use
 107 it with the familiar `Println()`, `Printf()`, etc. For example:
 108
 109 ```go
 110 stdLogger := appLogger.StandardLogger(&hclog.StandardLoggerOptions{
 111         InferLevels: true,
 112 })
 113 // Printf() is provided by stdlib log.Logger interface, not hclog.Logger
 114 stdLogger.Printf("[DEBUG] %+v", stdLogger)
 115 ```
 116
 117 ```text
 118 ... [DEBUG] my-app: &{mu:{state:0 sema:0} prefix: flag:0 out:0xc42000a0a0 buf:[]}
 119 ```
 120
 121 Notice that if `appLogger` is initialized with the `INFO` log level _and_ you
 122 specify `InferLevels: true`, you will not see any output here. You must change
 123 `appLogger` to `DEBUG` to see output. See the docs for more information.