diff --git a/CHANGELOG.md b/CHANGELOG.md index 7567f612..431fc9cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,13 @@ # 1.8.1 + Code quality: - * move magefile in its own subdir/submodule to remove magefile dependency on logrus consumer - * improve timestamp format documentation + +* move magefile in its own subdir/submodule to remove magefile dependency on logrus consumer +* improve timestamp format documentation Fixes: - * fix race condition on logger hooks +* fix race condition on logger hooks # 1.8.0 @@ -16,123 +18,153 @@ Correct versioning number replacing v1.7.1. Beware this release has introduced a new public API and its semver is therefore incorrect. Code quality: - * use go 1.15 in travis - * use magefile as task runner + +* use go 1.15 in travis +* use magefile as task runner Fixes: - * small fixes about new go 1.13 error formatting system - * Fix for long time race condiction with mutating data hooks + +* small fixes about new go 1.13 error formatting system +* Fix for long time race condiction with mutating data hooks Features: - * build support for zos + +* build support for zos # 1.7.0 + Fixes: - * the dependency toward a windows terminal library has been removed + +* the dependency toward a windows terminal library has been removed Features: - * a new buffer pool management API has been added - * a set of `Fn()` functions have been added + +* a new buffer pool management API has been added +* a set of `Fn()` functions have been added # 1.6.0 + Fixes: - * end of line cleanup - * revert the entry concurrency bug fix whic leads to deadlock under some circumstances - * update dependency on go-windows-terminal-sequences to fix a crash with go 1.14 + +* end of line cleanup +* revert the entry concurrency bug fix whic leads to deadlock under some circumstances +* update dependency on go-windows-terminal-sequences to fix a crash with go 1.14 Features: - * add an option to the `TextFormatter` to completely disable fields quoting + +* add an option to the `TextFormatter` to completely disable fields quoting # 1.5.0 + Code quality: - * add golangci linter run on travis + +* add golangci linter run on travis Fixes: - * add mutex for hooks concurrent access on `Entry` data - * caller function field for go1.14 - * fix build issue for gopherjs target + +* add mutex for hooks concurrent access on `Entry` data +* caller function field for go1.14 +* fix build issue for gopherjs target Feature: - * add an hooks/writer sub-package whose goal is to split output on different stream depending on the trace level - * add a `DisableHTMLEscape` option in the `JSONFormatter` - * add `ForceQuote` and `PadLevelText` options in the `TextFormatter` + +* add an hooks/writer sub-package whose goal is to split output on different stream depending on the trace level +* add a `DisableHTMLEscape` option in the `JSONFormatter` +* add `ForceQuote` and `PadLevelText` options in the `TextFormatter` # 1.4.2 - * Fixes build break for plan9, nacl, solaris + +* Fixes build break for plan9, nacl, solaris + # 1.4.1 + This new release introduces: - * Enhance TextFormatter to not print caller information when they are empty (#944) - * Remove dependency on golang.org/x/crypto (#932, #943) + +* Enhance TextFormatter to not print caller information when they are empty (#944) +* Remove dependency on golang.org/x/crypto (#932, #943) Fixes: - * Fix Entry.WithContext method to return a copy of the initial entry (#941) + +* Fix Entry.WithContext method to return a copy of the initial entry (#941) # 1.4.0 + This new release introduces: - * Add `DeferExitHandler`, similar to `RegisterExitHandler` but prepending the handler to the list of handlers (semantically like `defer`) (#848). - * Add `CallerPrettyfier` to `JSONFormatter` and `TextFormatter` (#909, #911) - * Add `Entry.WithContext()` and `Entry.Context`, to set a context on entries to be used e.g. in hooks (#919). + +* Add `DeferExitHandler`, similar to `RegisterExitHandler` but prepending the handler to the list of handlers (semantically like `defer`) (#848). +* Add `CallerPrettyfier` to `JSONFormatter` and `TextFormatter` (#909, #911) +* Add `Entry.WithContext()` and `Entry.Context`, to set a context on entries to be used e.g. in hooks (#919). Fixes: - * Fix wrong method calls `Logger.Print` and `Logger.Warningln` (#893). - * Update `Entry.Logf` to not do string formatting unless the log level is enabled (#903) - * Fix infinite recursion on unknown `Level.String()` (#907) - * Fix race condition in `getCaller` (#916). +* Fix wrong method calls `Logger.Print` and `Logger.Warningln` (#893). +* Update `Entry.Logf` to not do string formatting unless the log level is enabled (#903) +* Fix infinite recursion on unknown `Level.String()` (#907) +* Fix race condition in `getCaller` (#916). # 1.3.0 + This new release introduces: - * Log, Logf, Logln functions for Logger and Entry that take a Level + +* Log, Logf, Logln functions for Logger and Entry that take a Level Fixes: - * Building prometheus node_exporter on AIX (#840) - * Race condition in TextFormatter (#468) - * Travis CI import path (#868) - * Remove coloured output on Windows (#862) - * Pointer to func as field in JSONFormatter (#870) - * Properly marshal Levels (#873) + +* Building prometheus node_exporter on AIX (#840) +* Race condition in TextFormatter (#468) +* Travis CI import path (#868) +* Remove coloured output on Windows (#862) +* Pointer to func as field in JSONFormatter (#870) +* Properly marshal Levels (#873) # 1.2.0 + This new release introduces: - * A new method `SetReportCaller` in the `Logger` to enable the file, line and calling function from which the trace has been issued - * A new trace level named `Trace` whose level is below `Debug` - * A configurable exit function to be called upon a Fatal trace - * The `Level` object now implements `encoding.TextUnmarshaler` interface + +* A new method `SetReportCaller` in the `Logger` to enable the file, line and calling function from which the trace has been issued +* A new trace level named `Trace` whose level is below `Debug` +* A configurable exit function to be called upon a Fatal trace +* The `Level` object now implements `encoding.TextUnmarshaler` interface # 1.1.1 + This is a bug fix release. - * fix the build break on Solaris - * don't drop a whole trace in JSONFormatter when a field param is a function pointer which can not be serialized + +* fix the build break on Solaris +* don't drop a whole trace in JSONFormatter when a field param is a function pointer which can not be serialized # 1.1.0 + This new release introduces: - * several fixes: - * a fix for a race condition on entry formatting - * proper cleanup of previously used entries before putting them back in the pool - * the extra new line at the end of message in text formatter has been removed - * a new global public API to check if a level is activated: IsLevelEnabled - * the following methods have been added to the Logger object - * IsLevelEnabled - * SetFormatter - * SetOutput - * ReplaceHooks - * introduction of go module - * an indent configuration for the json formatter - * output colour support for windows - * the field sort function is now configurable for text formatter - * the CLICOLOR and CLICOLOR\_FORCE environment variable support in text formater + +* several fixes: + * a fix for a race condition on entry formatting + * proper cleanup of previously used entries before putting them back in the pool + * the extra new line at the end of message in text formatter has been removed +* a new global public API to check if a level is activated: IsLevelEnabled +* the following methods have been added to the Logger object + * IsLevelEnabled + * SetFormatter + * SetOutput + * ReplaceHooks +* introduction of go module +* an indent configuration for the json formatter +* output colour support for windows +* the field sort function is now configurable for text formatter +* the CLICOLOR and CLICOLOR\_FORCE environment variable support in text formater # 1.0.6 This new release introduces: - * a new api WithTime which allows to easily force the time of the log entry + +* a new api WithTime which allows to easily force the time of the log entry which is mostly useful for logger wrapper - * a fix reverting the immutability of the entry given as parameter to the hooks +* a fix reverting the immutability of the entry given as parameter to the hooks a new configuration field of the json formatter in order to put all the fields in a nested dictionnary - * a new SetOutput method in the Logger - * a new configuration of the textformatter to configure the name of the default keys - * a new configuration of the text formatter to disable the level truncation +* a new SetOutput method in the Logger +* a new configuration of the textformatter to configure the name of the default keys +* a new configuration of the text formatter to disable the level truncation # 1.0.5 @@ -215,7 +247,6 @@ This new release introduces: * logrus/core: fix possible race (#216) * logrus/doc: small typo fixes and doc improvements - # 0.8.6 * hooks/raven: allow passing an initialized client diff --git a/README.md b/README.md index b042c896..6801226d 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ the last thing you want from your Logging library (again...). This does not mean Logrus is dead. Logrus will continue to be maintained for security, (backwards compatible) bug fixes, and performance (where we are -limited by the interface). +limited by the interface). I believe Logrus' biggest contribution is to have played a part in today's widespread use of structured logging in Golang. There doesn't seem to be a @@ -72,21 +72,24 @@ time="2015-03-26T01:27:38-04:00" level=debug msg="Temperature changes" temperatu time="2015-03-26T01:27:38-04:00" level=panic msg="It's over 9000!" animal=orca size=9009 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 ``` + To ensure this behaviour even if a TTY is attached, set your formatter as follows: ```go - log.SetFormatter(&log.TextFormatter{ - DisableColors: true, - FullTimestamp: true, - }) + log.SetFormatter(&log.TextFormatter{ + DisableColors: true, + FullTimestamp: true, + }) ``` #### Logging Method Name If you wish to add the calling method as a field, instruct the logger via: + ```go log.SetReportCaller(true) ``` + This adds the caller as 'method' like so: ```json @@ -97,14 +100,15 @@ This adds the caller as 'method' like so: ```text time="2015-03-26T01:27:38-04:00" level=fatal method=github.com/sirupsen/arcticcreatures.migrate msg="a penguin swims by" animal=penguin ``` + Note that this does add measurable overhead - the cost will depend on the version of Go, but is between 20 and 40% in recent tests with 1.6 and 1.7. You can validate this in your -environment via benchmarks: -``` +environment via benchmarks: + +```bash go test -bench=.*CallerTracing ``` - #### Case-sensitivity The organization's name was changed to lower-case--and this will not be changed @@ -285,11 +289,11 @@ func init() { } } ``` + 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). A list of currently known service hooks can be found in this wiki [page](https://github.com/sirupsen/logrus/wiki/Hooks) - #### Level logging Logrus has seven logging levels: Trace, Debug, Info, Warning, Error, Fatal and Panic. @@ -363,7 +367,7 @@ The built-in logging formatters are: * `logrus.TextFormatter`. Logs the event in colors if stdout is a tty, otherwise without colors. - * *Note:* to force colored output when there is no TTY, set the `ForceColors` + * _Note:_ to force colored output when there is no TTY, set the `ForceColors` field to `true`. To force no colored output even if there is a TTY set the `DisableColors` field to `true`. For Windows, see [github.com/mattn/go-colorable](https://github.com/mattn/go-colorable). @@ -486,7 +490,7 @@ level message is logged. The registered handlers will be executed before logrus performs an `os.Exit(1)`. This behavior may be helpful if callers need 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. -``` +```go ... handler := func() { // gracefully shutdown something... @@ -510,4 +514,4 @@ Situation when locking is not needed includes: 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) - (Refer to http://www.notthewizard.com/2014/06/17/are-files-appends-really-atomic/) + (Refer to )