-
Notifications
You must be signed in to change notification settings - Fork 81
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: clarify Error semantic #119
Conversation
cc @wojas |
98149a7
to
c704d3f
Compare
This is not how I have interpreted the interface, as discussed in #118. I would argue that not checking the level in |
The README and Dave's post do suggest that your interpretation is the correct one:
This does lead to two unfortunate usability issues:
|
Do you know what that extra information is in actual implementations? A stack backtrace might be a candidate, but IMHO that's not really useful because it will identify the location where the error gets logged, not where it occurred. |
Since Go 1.13, an error can wrap another error, and this can be unwrapped. I'm not sure if this is actually useful in logging, as the final error message will typically include all the nested information. |
Wrapped errors as values can and probably will be handled the same way in |
It probably would have been nicer if the signatures of Then you could do:
Adding Anyway, I think it's good to clarify this in the docs. |
9a82c6f
to
3398e57
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nits on words.
logr.go
Outdated
// information (such as stack traces) on calls to Error(). Another difference | ||
// is that error messages always get emitted, regardless of the current | ||
// verbosity. This can also be used when no error instance is available | ||
// by calling Error with nil as err parameter. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd cut words:
"""
...on calls to Error(). Error() messages are always logged, regardless of the current verbosity. If there is no error instance available, passing nil is valid.
"""
logr.go
Outdated
@@ -253,11 +257,12 @@ func (l Logger) Info(msg string, keysAndValues ...interface{}) { | |||
// Error logs an error, with the given message and key/value pairs as context. | |||
// It functions similarly to Info, but may have unique behavior, and should be | |||
// preferred for logging errors (see the package documentations for more | |||
// information). | |||
// information). The log message will always be emitted, regardless of verbosity level. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
linewrap? Can't tell for sure but it looks long
logr.go
Outdated
// | ||
// The msg argument should be used to add context to any underlying error, | ||
// while the err argument should be used to attach the actual error that | ||
// triggered this log line, if present. | ||
// triggered this log line, if present. The err parameter is optional | ||
// and nil can be passed instead of an error instance. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/can/may/
Two aspects were not spelled out explicitly, which sometimes led to misunderstandings: - error messages are always printed - the error instance is optional
3398e57
to
f8fce6a
Compare
@thockin Nits addressed and commit updated, please take another look. |
Two aspects were not spelled out explicitly, which sometimes led to
misunderstandings:
Fixes: #118