Debian Codegraph @

logging/log.go

raw
1 package logging
2
3 import (
4 "fmt"
5 "io"
6 "os"
7 "time"
8 )
9
10 // Logger provides a standardised logging interface.
11 type Logger interface {
12 // SetLevel sets the minimum log level.
13 SetLevel(Level)
14
15 // Good returns true if the Logger is healthy.
16 Good() bool
17
18 // Status returns an error corresponding to the logger's state;
19 // if it's healthy (e.g. Good() returns true), Error will
20 // return nil.
21 Status() error
22
23 // Close gives the Logger the opportunity to perform any cleanup.
24 Close()
25
26 // Log messages consist of four components:
27 //
28 // 1. The **level** attaches a notion of priority to the log message.
29 // Several log levels are available:
30 //
31 // + FATAL (32): the system is in an unsuable state, and cannot
32 // continue to run. Most of the logging for this will cause the
33 // program to exit with an error code.
34 // + CRITICAL (16): critical conditions. The error, if uncorrected, is
35 // likely to cause a fatal condition shortly. An example is running
36 // out of disk space. This is something that the ops team should get
37 // paged for.
38 // + ERROR (8): error conditions. A single error doesn't require an
39 // ops team to be paged, but repeated errors should often trigger a
40 // page based on threshold triggers. An example is a network
41 // failure: it might be a transient failure (these do happen), but
42 // most of the time it's self-correcting.
43 // + WARNING (4): warning conditions. An example of this is a bad
44 // request sent to a server. This isn't an error on the part of the
45 // program, but it may be indicative of other things. Like errors,
46 // the ops team shouldn't be paged for errors, but a page might be
47 // triggered if a certain threshold of warnings is reached (which is
48 // typically much higher than errors). For example, repeated
49 // warnings might be a sign that the system is under attack.
50 // + INFO (2): informational message. This is a normal log message
51 // that is used to deliver information, such as recording
52 // requests. Ops teams are never paged for informational
53 // messages. This is the default log level.
54 // + DEBUG (1): debug-level message. These are only used during
55 // development or if a deployed system repeatedly sees abnormal
56 // errors.
57 //
58 // The numeric values indicate the priority of a given level.
59 //
60 // 2. The **actor** is used to specify which component is generating
61 // the log message. This could be the program name, or it could be
62 // a specific component inside the system.
63 //
64 // 3. The **event** is a short message indicating what happened. This is
65 // most like the traditional log message.
66 //
67 // 4. The **attributes** are an optional set of key-value string pairs that
68 // provide additional information.
69 //
70 // Additionally, each log message has an associated timestamp. For the
71 // text-based logs, this is "%FT%T%z"; for the binary logs, this is a
72 // 64-bit Unix timestamp. An example text-based timestamp might look like ::
73 //
74 // [2016-03-27T20:59:27-0700] [INFO] [actor:server event:request received] client=192.168.2.5 request-size=839
75 //
76 // Note that this is organised in a manner that facilitates parsing::
77 //
78 // /\[(\d{4}-\d{3}-\d{2}T\d{2}:\d{2}:\d{2}[+-]\d{4})\] \[(\w+\)]\) \[actor:(.+?) event:(.+?)\]/
79 //
80 // will cover the header:
81 //
82 // + ``$1`` contains the timestamp
83 // + ``$2`` contains the level
84 // + ``$3`` contains the actor
85 // + ``$4`` contains the event
86 Debug(actor, event string, attrs map[string]string)
87 Info(actor, event string, attrs map[string]string)
88 Warn(actor, event string, attrs map[string]string)
89 Error(actor, event string, attrs map[string]string)
90 Critical(actor, event string, attrs map[string]string)
91 Fatal(actor, event string, attrs map[string]string)
92 FatalCode(exitcode int, actor, event string, attrs map[string]string)
93 FatalNoDie(actor, event string, attrs map[string]string)
94 }
95
96 // A LogWriter is a Logger that operates on an io.Writer.
97 type LogWriter struct {
98 wo, we io.Writer
99 lvl Level
100 state error
101 snl bool // suppress newline
102 }
103
104 // NewLogWriter takes an output writer (wo) and an error writer (we),
105 // and produces a new Logger. If the error writer is nil, error logs
106 // will be multiplexed onto the output writer.
107 func NewLogWriter(wo, we io.Writer) *LogWriter {
108 if we == nil {
109 we = wo
110 }
111
112 return &LogWriter{
113 wo: wo,
114 we: we,
115 lvl: DefaultLevel,
116 state: nil,
117 }
118 }
119
120 func (lw *LogWriter) output(w io.Writer, lvl Level, actor, event string, attrs map[string]string) {
121 t := time.Now().Format(DateFormat)
122 fmt.Fprintf(w, "[%s] [%s] [actor:%s event:%s]", t, levelPrefix[lvl], actor, event)
123 for k, v := range attrs {
124 fmt.Fprintf(w, " %s=%s", k, v)
125 }
126
127 if !lw.snl {
128 fmt.Fprintf(w, "\n")
129 }
130 }
131
132 // Debug emits a debug-level message. These are only used during
133 // development or if a deployed system repeatedly sees abnormal
134 // errors.
135 //
136 // Actor specifies the component emitting the message; event indicates
137 // the event that caused the log message to be emitted. attrs is a map
138 // of key-value string pairs that can be used to provide additional
139 // information.
140 func (lw *LogWriter) Debug(actor, event string, attrs map[string]string) {
141 if lw.lvl > LevelDebug {
142 return
143 }
144 lw.output(lw.wo, LevelDebug, actor, event, attrs)
145 }
146
147 // Info emits an informational message. This is a normal log message
148 // that is used to deliver information, such as recording
149 // requests. Ops teams are never paged for informational
150 // messages. This is the default log level.
151 //
152 // Actor specifies the component emitting the message; event indicates
153 // the event that caused the log message to be emitted. attrs is a map
154 // of key-value string pairs that can be used to provide additional
155 // information.
156 func (lw *LogWriter) Info(actor, event string, attrs map[string]string) {
157 if lw.lvl > LevelInfo {
158 return
159 }
160 lw.output(lw.wo, LevelInfo, actor, event, attrs)
161 }
162
163 // Warn emits a warning message. An example of this is a bad request
164 // sent to a server. This isn't an error on the part of the program,
165 // but it may be indicative of other things. Like errors, the ops team
166 // shouldn't be paged for errors, but a page might be triggered if a
167 // certain threshold of warnings is reached (which is typically much
168 // higher than errors). For example, repeated warnings might be a sign
169 // that the system is under attack.
170 //
171 // Actor specifies the component emitting the message; event indicates
172 // the event that caused the log message to be emitted. attrs is a map
173 // of key-value string pairs that can be used to provide additional
174 // information.
175 func (lw *LogWriter) Warn(actor, event string, attrs map[string]string) {
176 if lw.lvl > LevelWarning {
177 return
178 }
179 lw.output(lw.we, LevelWarning, actor, event, attrs)
180 }
181
182 // Error emits an error message. A single error doesn't require an ops
183 // team to be paged, but repeated errors should often trigger a page
184 // based on threshold triggers. An example is a network failure: it
185 // might be a transient failure (these do happen), but most of the
186 // time it's self-correcting.
187 //
188 // Actor specifies the component emitting the message; event indicates
189 // the event that caused the log message to be emitted. attrs is a map
190 // of key-value string pairs that can be used to provide additional
191 // information.
192 func (lw *LogWriter) Error(actor, event string, attrs map[string]string) {
193 if lw.lvl > LevelError {
194 return
195 }
196 lw.output(lw.we, LevelError, actor, event, attrs)
197 }
198
199 // Critical emits a message indicating a critical condition. The
200 // error, if uncorrected, is likely to cause a fatal condition
201 // shortly. An example is running out of disk space. This is
202 // something that the ops team should get paged for.
203 //
204 // Actor specifies the component emitting the message; event indicates
205 // the event that caused the log message to be emitted. attrs is a map
206 // of key-value string pairs that can be used to provide additional
207 // information.
208 func (lw *LogWriter) Critical(actor, event string, attrs map[string]string) {
209 if lw.lvl > LevelCritical {
210 return
211 }
212 lw.output(lw.we, LevelCritical, actor, event, attrs)
213 }
214
215 // Fatal emits a message indicating that the system is in an unsuable
216 // state, and cannot continue to run. The program will exit with exit
217 // code 1.
218 //
219 // Actor specifies the component emitting the message; event indicates
220 // the event that caused the log message to be emitted. attrs is a map
221 // of key-value string pairs that can be used to provide additional
222 // information.
223 func (lw *LogWriter) Fatal(actor, event string, attrs map[string]string) {
224 if lw.lvl > LevelFatal {
225 return
226 }
227 lw.output(lw.we, LevelFatal, actor, event, attrs)
228 os.Exit(1)
229 }
230
231 // Fatal emits a message indicating that the system is in an unsuable
232 // state, and cannot continue to run. The program will exit with the
233 // exit code speicfied in the exitcode argument.
234 //
235 // Actor specifies the component emitting the message; event indicates
236 // the event that caused the log message to be emitted. attrs is a map
237 // of key-value string pairs that can be used to provide additional
238 // information.
239 func (lw *LogWriter) FatalCode(exitcode int, actor, event string, attrs map[string]string) {
240 if lw.lvl > LevelFatal {
241 return
242 }
243 lw.output(lw.we, LevelFatal, actor, event, attrs)
244 os.Exit(exitcode)
245 }
246
247 // Fatal emits a message indicating that the system is in an unsuable
248 // state, and cannot continue to run. The program will not exit; it is
249 // assumed that the caller has some final clean up to perform.
250 //
251 // Actor specifies the component emitting the message; event indicates
252 // the event that caused the log message to be emitted. attrs is a map
253 // of key-value string pairs that can be used to provide additional
254 // information.
255 func (lw *LogWriter) FatalNoDie(actor, event string, attrs map[string]string) {
256 if lw.lvl > LevelFatal {
257 return
258 }
259 lw.output(lw.we, LevelFatal, actor, event, attrs)
260 }
261
262 // Good returns true if the logger is healthy.
263 func (lw *LogWriter) Good() bool {
264 return lw.state == nil
265 }
266
267 // Status returns an error value from the logger if it isn't healthy,
268 // or nil if the logger is healthy.
269 func (lw *LogWriter) Status() error {
270 return lw.state
271 }
272
273 // SetLevel changes the log level.
274 func (lw *LogWriter) SetLevel(l Level) {
275 lw.lvl = l
276 }
277
278 // Close is a no-op that satisfies the Logger interface.
279 func (lw *LogWriter) Close() {}