mirror of https://github.com/apache/lucene.git
66 lines
2.8 KiB
Plaintext
66 lines
2.8 KiB
Plaintext
Using log calls
|
|
===============
|
|
|
|
There are several hidden gotchas when using logging. The main
|
|
problem is that certain patterns are evaluated and objects
|
|
constructed even if the logging level is more restrictive
|
|
than this call. If the logging level is WARN, then the following
|
|
log.info patterns are evaluated and never-used objects are
|
|
created even though the message is never logged.
|
|
|
|
This can be very expensive as per measurements with Java Flight
|
|
Recorder. It's particularly egregious when complex operations
|
|
are performed for, say, log.debug or trace calls, which
|
|
are rarely actually used.
|
|
|
|
- log.info("some stuff " + some_object) will concatenate the
|
|
strings and create an object. some_object is anytying except
|
|
a string constant, i.e. something enclosed in quotes.
|
|
|
|
- log.info("some stuff {}", object.method()) will execute the
|
|
method.
|
|
|
|
- log.info("some stuff {}", object.toString()) will execute
|
|
the toString and then throw the results away.
|
|
|
|
-----------
|
|
NOTES:
|
|
|
|
- If you're creating a logging call that has no choice but to
|
|
do something expensive, surround it with "if (log.is*Enabled)".
|
|
|
|
- Logging calls can take a bare exception, but do not
|
|
use the braces if you want the stack trace! So
|
|
log.info("stuff {}", exception) will not print the full stack,
|
|
log.info("stuff ", exception) _will_ print the full stack.
|
|
log.inf0("stuff {} ", some_object, exception) will print the full stack.
|
|
If you're puzzled as to why so many logging calls don't have a matching
|
|
number of curly-braces and parameters, this is usually why if they involve
|
|
exceptions.
|
|
|
|
- When slf4j supports lambdas in logging calls (log4j2 does now),
|
|
we can use lambdas rather than "if log.is*Enabled". slf4j 2.0
|
|
will when released.
|
|
|
|
- warn, error, and fatal level messages are NOT flagged. However, if you want to
|
|
check these levels for including '+', specify '-PcheckPlus=true'. This is more
|
|
a style than functional check.
|
|
|
|
- You can get into some pretty convolued consructs trying to pass some of these
|
|
checks. Adding //logok, with or without spaces will cause the line to pass
|
|
no matter what. Please use this hack sparingly.
|
|
|
|
- String constants may be added with '+' OK, but they _must_ be literal strings.
|
|
The compiler is smart enough to concatenate them when compiling. For example:
|
|
log.info("some {} "+ "more nonsense {}", object1, object2) is fine.
|
|
log.info("some{} " + " more nonsense " + object1, object2) is NOT fine.
|
|
|
|
For a fuller discussion, see LUCENE-7788 and the other JIRAs linked
|
|
from there.
|
|
|
|
Until we get all the calls cleaned up, you MUST specify -PsrcDir=relative_path,
|
|
e.g. '-PsrcDir=solr/core/src/java/org/apache/solr/core'. This task will
|
|
recursively check all '*.java. files under that directory. Actually, it
|
|
just checks any file whose AbsolutePath contains the specification. May be
|
|
comma-delimited.
|