]>
Commit | Line | Data |
---|---|---|
15c0b25d AP |
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. |