lucene/help/validateLogCalls.txt

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 other stuff") will concatenate the
  strings and create an object 

- 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.

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.