Document logging stuff

[originalfoo]

I'll create a markdown doc with notes about best practice for logging seeing as it turned out to be more nuanced than we originally expected.

Some details in this comment: #349 (comment)

@kvakvs Can you comment with some notes on the Format method(s) you added to the Log class? Which situations is it best to use those?

I'll do a draft of the doc and send a PR for review.

[kvakvs]

• Log.Trace, Log.Debug, Log.Info, Log.Warning, Log.Error -- these format the message in place,
  • ✔ Cheap if there is a const string or a very simple format call with a few args.
  • ✔ Cheap if wrapped in an if (booleanValue) { ... }
  • Log.Debug and Log.Trace are optimized away if not in Debug mode
  • ⚠ Expensive if multiple $"string {interpolations}" are used (like breaking into multiple lines)
• Log.DebugFormat, Log.InfoFormat, ... - these format message later, when logging. Good for very-very long format strings with multiple complex arguments.
  • ✔ As they use format string literal, it can be split multiple lines without perf penalty
  • 💲 The cost incurred: bulding args array (with pointers)
  • Prevents multiple calls to string.Format as opposed to multiline $"string {interpolations}"
  • Log.DebugFormat is optimized away, others are not, so is a good idea to wrap in if (boolValue)
  • ⚠ Expensive if not wrapped in a if () condition
• Log.DebugIf, Log.WarningIf, ... - these first check a condition, and then call a lambda, which provides a formatted string.
  • ✔ Lambda building is just as cheap as format args building
  • 💲 The cost incurred: each captured variable (pointer) is copied into lambda
  • ✔ Actual string is formatted ONLY if the condition holds true
  • Log.DebugIf is optimized away if not in Debug mode
  • ⚠ Cannot capture out and ref values
• Log.NotImpl logs an error if something is not implemented and only in debug mode

[dymanoid]

each captured value is copied into lambda

This is not true. A lambda captures a variable, not a value.

[kvakvs]

A pointer.
Does not matter when the log is executed right away and everything is still equal to their expected values, but this might be important when the log is deferred to logging thread and the string value is produced later.

[dymanoid]

A pointer.

Well... Not a pointer. Semantically - a variable. It's better to think this way. For a reference type, this will be a reference. For a value type, this will be a struct copy indeed. (Which might cause unexpected behavior, but it's off-topic for this issue.)