diff options
Diffstat (limited to 'vendor/github.com/sirupsen/logrus/README.md')
-rw-r--r-- | vendor/github.com/sirupsen/logrus/README.md | 515 |
1 files changed, 0 insertions, 515 deletions
diff --git a/vendor/github.com/sirupsen/logrus/README.md b/vendor/github.com/sirupsen/logrus/README.md deleted file mode 100644 index d1d4a85..0000000 --- a/vendor/github.com/sirupsen/logrus/README.md +++ /dev/null | |||
@@ -1,515 +0,0 @@ | |||
1 | # Logrus <img src="http://i.imgur.com/hTeVwmJ.png" width="40" height="40" alt=":walrus:" class="emoji" title=":walrus:"/> [![Build Status](https://github.com/sirupsen/logrus/workflows/CI/badge.svg)](https://github.com/sirupsen/logrus/actions?query=workflow%3ACI) [![Build Status](https://travis-ci.org/sirupsen/logrus.svg?branch=master)](https://travis-ci.org/sirupsen/logrus) [![Go Reference](https://pkg.go.dev/badge/github.com/sirupsen/logrus.svg)](https://pkg.go.dev/github.com/sirupsen/logrus) | ||
2 | |||
3 | Logrus is a structured logger for Go (golang), completely API compatible with | ||
4 | the standard library logger. | ||
5 | |||
6 | **Logrus is in maintenance-mode.** We will not be introducing new features. It's | ||
7 | simply too hard to do in a way that won't break many people's projects, which is | ||
8 | the last thing you want from your Logging library (again...). | ||
9 | |||
10 | This does not mean Logrus is dead. Logrus will continue to be maintained for | ||
11 | security, (backwards compatible) bug fixes, and performance (where we are | ||
12 | limited by the interface). | ||
13 | |||
14 | I believe Logrus' biggest contribution is to have played a part in today's | ||
15 | widespread use of structured logging in Golang. There doesn't seem to be a | ||
16 | reason to do a major, breaking iteration into Logrus V2, since the fantastic Go | ||
17 | community has built those independently. Many fantastic alternatives have sprung | ||
18 | up. Logrus would look like those, had it been re-designed with what we know | ||
19 | about structured logging in Go today. Check out, for example, | ||
20 | [Zerolog][zerolog], [Zap][zap], and [Apex][apex]. | ||
21 | |||
22 | [zerolog]: https://github.com/rs/zerolog | ||
23 | [zap]: https://github.com/uber-go/zap | ||
24 | [apex]: https://github.com/apex/log | ||
25 | |||
26 | **Seeing weird case-sensitive problems?** It's in the past been possible to | ||
27 | import Logrus as both upper- and lower-case. Due to the Go package environment, | ||
28 | this caused issues in the community and we needed a standard. Some environments | ||
29 | experienced problems with the upper-case variant, so the lower-case was decided. | ||
30 | Everything using `logrus` will need to use the lower-case: | ||
31 | `github.com/sirupsen/logrus`. Any package that isn't, should be changed. | ||
32 | |||
33 | To fix Glide, see [these | ||
34 | comments](https://github.com/sirupsen/logrus/issues/553#issuecomment-306591437). | ||
35 | For an in-depth explanation of the casing issue, see [this | ||
36 | comment](https://github.com/sirupsen/logrus/issues/570#issuecomment-313933276). | ||
37 | |||
38 | Nicely color-coded in development (when a TTY is attached, otherwise just | ||
39 | plain text): | ||
40 | |||
41 | ![Colored](http://i.imgur.com/PY7qMwd.png) | ||
42 | |||
43 | With `log.SetFormatter(&log.JSONFormatter{})`, for easy parsing by logstash | ||
44 | or Splunk: | ||
45 | |||
46 | ```text | ||
47 | {"animal":"walrus","level":"info","msg":"A group of walrus emerges from the | ||
48 | ocean","size":10,"time":"2014-03-10 19:57:38.562264131 -0400 EDT"} | ||
49 | |||
50 | {"level":"warning","msg":"The group's number increased tremendously!", | ||
51 | "number":122,"omg":true,"time":"2014-03-10 19:57:38.562471297 -0400 EDT"} | ||
52 | |||
53 | {"animal":"walrus","level":"info","msg":"A giant walrus appears!", | ||
54 | "size":10,"time":"2014-03-10 19:57:38.562500591 -0400 EDT"} | ||
55 | |||
56 | {"animal":"walrus","level":"info","msg":"Tremendously sized cow enters the ocean.", | ||
57 | "size":9,"time":"2014-03-10 19:57:38.562527896 -0400 EDT"} | ||
58 | |||
59 | {"level":"fatal","msg":"The ice breaks!","number":100,"omg":true, | ||
60 | "time":"2014-03-10 19:57:38.562543128 -0400 EDT"} | ||
61 | ``` | ||
62 | |||
63 | With the default `log.SetFormatter(&log.TextFormatter{})` when a TTY is not | ||
64 | attached, the output is compatible with the | ||
65 | [logfmt](http://godoc.org/github.com/kr/logfmt) format: | ||
66 | |||
67 | ```text | ||
68 | time="2015-03-26T01:27:38-04:00" level=debug msg="Started observing beach" animal=walrus number=8 | ||
69 | time="2015-03-26T01:27:38-04:00" level=info msg="A group of walrus emerges from the ocean" animal=walrus size=10 | ||
70 | time="2015-03-26T01:27:38-04:00" level=warning msg="The group's number increased tremendously!" number=122 omg=true | ||
71 | time="2015-03-26T01:27:38-04:00" level=debug msg="Temperature changes" temperature=-4 | ||
72 | time="2015-03-26T01:27:38-04:00" level=panic msg="It's over 9000!" animal=orca size=9009 | ||
73 | time="2015-03-26T01:27:38-04:00" level=fatal msg="The ice breaks!" err=&{0x2082280c0 map[animal:orca size:9009] 2015-03-26 01:27:38.441574009 -0400 EDT panic It's over 9000!} number=100 omg=true | ||
74 | ``` | ||
75 | To ensure this behaviour even if a TTY is attached, set your formatter as follows: | ||
76 | |||
77 | ```go | ||
78 | log.SetFormatter(&log.TextFormatter{ | ||
79 | DisableColors: true, | ||
80 | FullTimestamp: true, | ||
81 | }) | ||
82 | ``` | ||
83 | |||
84 | #### Logging Method Name | ||
85 | |||
86 | If you wish to add the calling method as a field, instruct the logger via: | ||
87 | ```go | ||
88 | log.SetReportCaller(true) | ||
89 | ``` | ||
90 | This adds the caller as 'method' like so: | ||
91 | |||
92 | ```json | ||
93 | {"animal":"penguin","level":"fatal","method":"github.com/sirupsen/arcticcreatures.migrate","msg":"a penguin swims by", | ||
94 | "time":"2014-03-10 19:57:38.562543129 -0400 EDT"} | ||
95 | ``` | ||
96 | |||
97 | ```text | ||
98 | time="2015-03-26T01:27:38-04:00" level=fatal method=github.com/sirupsen/arcticcreatures.migrate msg="a penguin swims by" animal=penguin | ||
99 | ``` | ||
100 | Note that this does add measurable overhead - the cost will depend on the version of Go, but is | ||
101 | between 20 and 40% in recent tests with 1.6 and 1.7. You can validate this in your | ||
102 | environment via benchmarks: | ||
103 | ``` | ||
104 | go test -bench=.*CallerTracing | ||
105 | ``` | ||
106 | |||
107 | |||
108 | #### Case-sensitivity | ||
109 | |||
110 | The organization's name was changed to lower-case--and this will not be changed | ||
111 | back. If you are getting import conflicts due to case sensitivity, please use | ||
112 | the lower-case import: `github.com/sirupsen/logrus`. | ||
113 | |||
114 | #### Example | ||
115 | |||
116 | The simplest way to use Logrus is simply the package-level exported logger: | ||
117 | |||
118 | ```go | ||
119 | package main | ||
120 | |||
121 | import ( | ||
122 | log "github.com/sirupsen/logrus" | ||
123 | ) | ||
124 | |||
125 | func main() { | ||
126 | log.WithFields(log.Fields{ | ||
127 | "animal": "walrus", | ||
128 | }).Info("A walrus appears") | ||
129 | } | ||
130 | ``` | ||
131 | |||
132 | Note that it's completely api-compatible with the stdlib logger, so you can | ||
133 | replace your `log` imports everywhere with `log "github.com/sirupsen/logrus"` | ||
134 | and you'll now have the flexibility of Logrus. You can customize it all you | ||
135 | want: | ||
136 | |||
137 | ```go | ||
138 | package main | ||
139 | |||
140 | import ( | ||
141 | "os" | ||
142 | log "github.com/sirupsen/logrus" | ||
143 | ) | ||
144 | |||
145 | func init() { | ||
146 | // Log as JSON instead of the default ASCII formatter. | ||
147 | log.SetFormatter(&log.JSONFormatter{}) | ||
148 | |||
149 | // Output to stdout instead of the default stderr | ||
150 | // Can be any io.Writer, see below for File example | ||
151 | log.SetOutput(os.Stdout) | ||
152 | |||
153 | // Only log the warning severity or above. | ||
154 | log.SetLevel(log.WarnLevel) | ||
155 | } | ||
156 | |||
157 | func main() { | ||
158 | log.WithFields(log.Fields{ | ||
159 | "animal": "walrus", | ||
160 | "size": 10, | ||
161 | }).Info("A group of walrus emerges from the ocean") | ||
162 | |||
163 | log.WithFields(log.Fields{ | ||
164 | "omg": true, | ||
165 | "number": 122, | ||
166 | }).Warn("The group's number increased tremendously!") | ||
167 | |||
168 | log.WithFields(log.Fields{ | ||
169 | "omg": true, | ||
170 | "number": 100, | ||
171 | }).Fatal("The ice breaks!") | ||
172 | |||
173 | // A common pattern is to re-use fields between logging statements by re-using | ||
174 | // the logrus.Entry returned from WithFields() | ||
175 | contextLogger := log.WithFields(log.Fields{ | ||
176 | "common": "this is a common field", | ||
177 | "other": "I also should be logged always", | ||
178 | }) | ||
179 | |||
180 | contextLogger.Info("I'll be logged with common and other field") | ||
181 | contextLogger.Info("Me too") | ||
182 | } | ||
183 | ``` | ||
184 | |||
185 | For more advanced usage such as logging to multiple locations from the same | ||
186 | application, you can also create an instance of the `logrus` Logger: | ||
187 | |||
188 | ```go | ||
189 | package main | ||
190 | |||
191 | import ( | ||
192 | "os" | ||
193 | "github.com/sirupsen/logrus" | ||
194 | ) | ||
195 | |||
196 | // Create a new instance of the logger. You can have any number of instances. | ||
197 | var log = logrus.New() | ||
198 | |||
199 | func main() { | ||
200 | // The API for setting attributes is a little different than the package level | ||
201 | // exported logger. See Godoc. | ||
202 | log.Out = os.Stdout | ||
203 | |||
204 | // You could set this to any `io.Writer` such as a file | ||
205 | // file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666) | ||
206 | // if err == nil { | ||
207 | // log.Out = file | ||
208 | // } else { | ||
209 | // log.Info("Failed to log to file, using default stderr") | ||
210 | // } | ||
211 | |||
212 | log.WithFields(logrus.Fields{ | ||
213 | "animal": "walrus", | ||
214 | "size": 10, | ||
215 | }).Info("A group of walrus emerges from the ocean") | ||
216 | } | ||
217 | ``` | ||
218 | |||
219 | #### Fields | ||
220 | |||
221 | Logrus encourages careful, structured logging through logging fields instead of | ||
222 | long, unparseable error messages. For example, instead of: `log.Fatalf("Failed | ||
223 | to send event %s to topic %s with key %d")`, you should log the much more | ||
224 | discoverable: | ||
225 | |||
226 | ```go | ||
227 | log.WithFields(log.Fields{ | ||
228 | "event": event, | ||
229 | "topic": topic, | ||
230 | "key": key, | ||
231 | }).Fatal("Failed to send event") | ||
232 | ``` | ||
233 | |||
234 | We've found this API forces you to think about logging in a way that produces | ||
235 | much more useful logging messages. We've been in countless situations where just | ||
236 | a single added field to a log statement that was already there would've saved us | ||
237 | hours. The `WithFields` call is optional. | ||
238 | |||
239 | In general, with Logrus using any of the `printf`-family functions should be | ||
240 | seen as a hint you should add a field, however, you can still use the | ||
241 | `printf`-family functions with Logrus. | ||
242 | |||
243 | #### Default Fields | ||
244 | |||
245 | Often it's helpful to have fields _always_ attached to log statements in an | ||
246 | application or parts of one. For example, you may want to always log the | ||
247 | `request_id` and `user_ip` in the context of a request. Instead of writing | ||
248 | `log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip})` on | ||
249 | every line, you can create a `logrus.Entry` to pass around instead: | ||
250 | |||
251 | ```go | ||
252 | requestLogger := log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip}) | ||
253 | requestLogger.Info("something happened on that request") # will log request_id and user_ip | ||
254 | requestLogger.Warn("something not great happened") | ||
255 | ``` | ||
256 | |||
257 | #### Hooks | ||
258 | |||
259 | You can add hooks for logging levels. For example to send errors to an exception | ||
260 | tracking service on `Error`, `Fatal` and `Panic`, info to StatsD or log to | ||
261 | multiple places simultaneously, e.g. syslog. | ||
262 | |||
263 | Logrus comes with [built-in hooks](hooks/). Add those, or your custom hook, in | ||
264 | `init`: | ||
265 | |||
266 | ```go | ||
267 | import ( | ||
268 | log "github.com/sirupsen/logrus" | ||
269 | "gopkg.in/gemnasium/logrus-airbrake-hook.v2" // the package is named "airbrake" | ||
270 | logrus_syslog "github.com/sirupsen/logrus/hooks/syslog" | ||
271 | "log/syslog" | ||
272 | ) | ||
273 | |||
274 | func init() { | ||
275 | |||
276 | // Use the Airbrake hook to report errors that have Error severity or above to | ||
277 | // an exception tracker. You can create custom hooks, see the Hooks section. | ||
278 | log.AddHook(airbrake.NewHook(123, "xyz", "production")) | ||
279 | |||
280 | hook, err := logrus_syslog.NewSyslogHook("udp", "localhost:514", syslog.LOG_INFO, "") | ||
281 | if err != nil { | ||
282 | log.Error("Unable to connect to local syslog daemon") | ||
283 | } else { | ||
284 | log.AddHook(hook) | ||
285 | } | ||
286 | } | ||
287 | ``` | ||
288 | Note: Syslog hook also support connecting to local syslog (Ex. "/dev/log" or "/var/run/syslog" or "/var/run/log"). For the detail, please check the [syslog hook README](hooks/syslog/README.md). | ||
289 | |||
290 | A list of currently known service hooks can be found in this wiki [page](https://github.com/sirupsen/logrus/wiki/Hooks) | ||
291 | |||
292 | |||
293 | #### Level logging | ||
294 | |||
295 | Logrus has seven logging levels: Trace, Debug, Info, Warning, Error, Fatal and Panic. | ||
296 | |||
297 | ```go | ||
298 | log.Trace("Something very low level.") | ||
299 | log.Debug("Useful debugging information.") | ||
300 | log.Info("Something noteworthy happened!") | ||
301 | log.Warn("You should probably take a look at this.") | ||
302 | log.Error("Something failed but I'm not quitting.") | ||
303 | // Calls os.Exit(1) after logging | ||
304 | log.Fatal("Bye.") | ||
305 | // Calls panic() after logging | ||
306 | log.Panic("I'm bailing.") | ||
307 | ``` | ||
308 | |||
309 | You can set the logging level on a `Logger`, then it will only log entries with | ||
310 | that severity or anything above it: | ||
311 | |||
312 | ```go | ||
313 | // Will log anything that is info or above (warn, error, fatal, panic). Default. | ||
314 | log.SetLevel(log.InfoLevel) | ||
315 | ``` | ||
316 | |||
317 | It may be useful to set `log.Level = logrus.DebugLevel` in a debug or verbose | ||
318 | environment if your application has that. | ||
319 | |||
320 | Note: If you want different log levels for global (`log.SetLevel(...)`) and syslog logging, please check the [syslog hook README](hooks/syslog/README.md#different-log-levels-for-local-and-remote-logging). | ||
321 | |||
322 | #### Entries | ||
323 | |||
324 | Besides the fields added with `WithField` or `WithFields` some fields are | ||
325 | automatically added to all logging events: | ||
326 | |||
327 | 1. `time`. The timestamp when the entry was created. | ||
328 | 2. `msg`. The logging message passed to `{Info,Warn,Error,Fatal,Panic}` after | ||
329 | the `AddFields` call. E.g. `Failed to send event.` | ||
330 | 3. `level`. The logging level. E.g. `info`. | ||
331 | |||
332 | #### Environments | ||
333 | |||
334 | Logrus has no notion of environment. | ||
335 | |||
336 | If you wish for hooks and formatters to only be used in specific environments, | ||
337 | you should handle that yourself. For example, if your application has a global | ||
338 | variable `Environment`, which is a string representation of the environment you | ||
339 | could do: | ||
340 | |||
341 | ```go | ||
342 | import ( | ||
343 | log "github.com/sirupsen/logrus" | ||
344 | ) | ||
345 | |||
346 | func init() { | ||
347 | // do something here to set environment depending on an environment variable | ||
348 | // or command-line flag | ||
349 | if Environment == "production" { | ||
350 | log.SetFormatter(&log.JSONFormatter{}) | ||
351 | } else { | ||
352 | // The TextFormatter is default, you don't actually have to do this. | ||
353 | log.SetFormatter(&log.TextFormatter{}) | ||
354 | } | ||
355 | } | ||
356 | ``` | ||
357 | |||
358 | This configuration is how `logrus` was intended to be used, but JSON in | ||
359 | production is mostly only useful if you do log aggregation with tools like | ||
360 | Splunk or Logstash. | ||
361 | |||
362 | #### Formatters | ||
363 | |||
364 | The built-in logging formatters are: | ||
365 | |||
366 | * `logrus.TextFormatter`. Logs the event in colors if stdout is a tty, otherwise | ||
367 | without colors. | ||
368 | * *Note:* to force colored output when there is no TTY, set the `ForceColors` | ||
369 | field to `true`. To force no colored output even if there is a TTY set the | ||
370 | `DisableColors` field to `true`. For Windows, see | ||
371 | [github.com/mattn/go-colorable](https://github.com/mattn/go-colorable). | ||
372 | * When colors are enabled, levels are truncated to 4 characters by default. To disable | ||
373 | truncation set the `DisableLevelTruncation` field to `true`. | ||
374 | * When outputting to a TTY, it's often helpful to visually scan down a column where all the levels are the same width. Setting the `PadLevelText` field to `true` enables this behavior, by adding padding to the level text. | ||
375 | * All options are listed in the [generated docs](https://godoc.org/github.com/sirupsen/logrus#TextFormatter). | ||
376 | * `logrus.JSONFormatter`. Logs fields as JSON. | ||
377 | * All options are listed in the [generated docs](https://godoc.org/github.com/sirupsen/logrus#JSONFormatter). | ||
378 | |||
379 | Third party logging formatters: | ||
380 | |||
381 | * [`FluentdFormatter`](https://github.com/joonix/log). Formats entries that can be parsed by Kubernetes and Google Container Engine. | ||
382 | * [`GELF`](https://github.com/fabienm/go-logrus-formatters). Formats entries so they comply to Graylog's [GELF 1.1 specification](http://docs.graylog.org/en/2.4/pages/gelf.html). | ||
383 | * [`logstash`](https://github.com/bshuster-repo/logrus-logstash-hook). Logs fields as [Logstash](http://logstash.net) Events. | ||
384 | * [`prefixed`](https://github.com/x-cray/logrus-prefixed-formatter). Displays log entry source along with alternative layout. | ||
385 | * [`zalgo`](https://github.com/aybabtme/logzalgo). Invoking the Power of Zalgo. | ||
386 | * [`nested-logrus-formatter`](https://github.com/antonfisher/nested-logrus-formatter). Converts logrus fields to a nested structure. | ||
387 | * [`powerful-logrus-formatter`](https://github.com/zput/zxcTool). get fileName, log's line number and the latest function's name when print log; Sava log to files. | ||
388 | * [`caption-json-formatter`](https://github.com/nolleh/caption_json_formatter). logrus's message json formatter with human-readable caption added. | ||
389 | |||
390 | You can define your formatter by implementing the `Formatter` interface, | ||
391 | requiring a `Format` method. `Format` takes an `*Entry`. `entry.Data` is a | ||
392 | `Fields` type (`map[string]interface{}`) with all your fields as well as the | ||
393 | default ones (see Entries section above): | ||
394 | |||
395 | ```go | ||
396 | type MyJSONFormatter struct { | ||
397 | } | ||
398 | |||
399 | log.SetFormatter(new(MyJSONFormatter)) | ||
400 | |||
401 | func (f *MyJSONFormatter) Format(entry *Entry) ([]byte, error) { | ||
402 | // Note this doesn't include Time, Level and Message which are available on | ||
403 | // the Entry. Consult `godoc` on information about those fields or read the | ||
404 | // source of the official loggers. | ||
405 | serialized, err := json.Marshal(entry.Data) | ||
406 | if err != nil { | ||
407 | return nil, fmt.Errorf("Failed to marshal fields to JSON, %w", err) | ||
408 | } | ||
409 | return append(serialized, '\n'), nil | ||
410 | } | ||
411 | ``` | ||
412 | |||
413 | #### Logger as an `io.Writer` | ||
414 | |||
415 | Logrus can be transformed into an `io.Writer`. That writer is the end of an `io.Pipe` and it is your responsibility to close it. | ||
416 | |||
417 | ```go | ||
418 | w := logger.Writer() | ||
419 | defer w.Close() | ||
420 | |||
421 | srv := http.Server{ | ||
422 | // create a stdlib log.Logger that writes to | ||
423 | // logrus.Logger. | ||
424 | ErrorLog: log.New(w, "", 0), | ||
425 | } | ||
426 | ``` | ||
427 | |||
428 | Each line written to that writer will be printed the usual way, using formatters | ||
429 | and hooks. The level for those entries is `info`. | ||
430 | |||
431 | This means that we can override the standard library logger easily: | ||
432 | |||
433 | ```go | ||
434 | logger := logrus.New() | ||
435 | logger.Formatter = &logrus.JSONFormatter{} | ||
436 | |||
437 | // Use logrus for standard log output | ||
438 | // Note that `log` here references stdlib's log | ||
439 | // Not logrus imported under the name `log`. | ||
440 | log.SetOutput(logger.Writer()) | ||
441 | ``` | ||
442 | |||
443 | #### Rotation | ||
444 | |||
445 | Log rotation is not provided with Logrus. Log rotation should be done by an | ||
446 | external program (like `logrotate(8)`) that can compress and delete old log | ||
447 | entries. It should not be a feature of the application-level logger. | ||
448 | |||
449 | #### Tools | ||
450 | |||
451 | | Tool | Description | | ||
452 | | ---- | ----------- | | ||
453 | |[Logrus Mate](https://github.com/gogap/logrus_mate)|Logrus mate is a tool for Logrus to manage loggers, you can initial logger's level, hook and formatter by config file, the logger will be generated with different configs in different environments.| | ||
454 | |[Logrus Viper Helper](https://github.com/heirko/go-contrib/tree/master/logrusHelper)|An Helper around Logrus to wrap with spf13/Viper to load configuration with fangs! And to simplify Logrus configuration use some behavior of [Logrus Mate](https://github.com/gogap/logrus_mate). [sample](https://github.com/heirko/iris-contrib/blob/master/middleware/logrus-logger/example) | | ||
455 | |||
456 | #### Testing | ||
457 | |||
458 | Logrus has a built in facility for asserting the presence of log messages. This is implemented through the `test` hook and provides: | ||
459 | |||
460 | * decorators for existing logger (`test.NewLocal` and `test.NewGlobal`) which basically just adds the `test` hook | ||
461 | * a test logger (`test.NewNullLogger`) that just records log messages (and does not output any): | ||
462 | |||
463 | ```go | ||
464 | import( | ||
465 | "github.com/sirupsen/logrus" | ||
466 | "github.com/sirupsen/logrus/hooks/test" | ||
467 | "github.com/stretchr/testify/assert" | ||
468 | "testing" | ||
469 | ) | ||
470 | |||
471 | func TestSomething(t*testing.T){ | ||
472 | logger, hook := test.NewNullLogger() | ||
473 | logger.Error("Helloerror") | ||
474 | |||
475 | assert.Equal(t, 1, len(hook.Entries)) | ||
476 | assert.Equal(t, logrus.ErrorLevel, hook.LastEntry().Level) | ||
477 | assert.Equal(t, "Helloerror", hook.LastEntry().Message) | ||
478 | |||
479 | hook.Reset() | ||
480 | assert.Nil(t, hook.LastEntry()) | ||
481 | } | ||
482 | ``` | ||
483 | |||
484 | #### Fatal handlers | ||
485 | |||
486 | Logrus can register one or more functions that will be called when any `fatal` | ||
487 | level message is logged. The registered handlers will be executed before | ||
488 | logrus performs an `os.Exit(1)`. This behavior may be helpful if callers need | ||
489 | to gracefully shutdown. Unlike a `panic("Something went wrong...")` call which can be intercepted with a deferred `recover` a call to `os.Exit(1)` can not be intercepted. | ||
490 | |||
491 | ``` | ||
492 | ... | ||
493 | handler := func() { | ||
494 | // gracefully shutdown something... | ||
495 | } | ||
496 | logrus.RegisterExitHandler(handler) | ||
497 | ... | ||
498 | ``` | ||
499 | |||
500 | #### Thread safety | ||
501 | |||
502 | By default, Logger is protected by a mutex for concurrent writes. The mutex is held when calling hooks and writing logs. | ||
503 | If you are sure such locking is not needed, you can call logger.SetNoLock() to disable the locking. | ||
504 | |||
505 | Situation when locking is not needed includes: | ||
506 | |||
507 | * You have no hooks registered, or hooks calling is already thread-safe. | ||
508 | |||
509 | * Writing to logger.Out is already thread-safe, for example: | ||
510 | |||
511 | 1) logger.Out is protected by locks. | ||
512 | |||
513 | 2) logger.Out is an os.File handler opened with `O_APPEND` flag, and every write is smaller than 4k. (This allows multi-thread/multi-process writing) | ||
514 | |||
515 | (Refer to http://www.notthewizard.com/2014/06/17/are-files-appends-really-atomic/) | ||