diff options
Diffstat (limited to 'vendor/github.com/hashicorp/go-hclog/README.md')
-rw-r--r-- | vendor/github.com/hashicorp/go-hclog/README.md | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/vendor/github.com/hashicorp/go-hclog/README.md b/vendor/github.com/hashicorp/go-hclog/README.md new file mode 100644 index 0000000..614342b --- /dev/null +++ b/vendor/github.com/hashicorp/go-hclog/README.md | |||
@@ -0,0 +1,123 @@ | |||
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. | ||