Logger docs: recommend using thunks for expensive computations

lib/logger/lib/logger.ex

@@ -19,6 +19,30 @@ defmodule Logger do
     * Wraps OTP's `error_logger` to prevent it from
       overflowing.
 
+  Logging is useful for tracking when an event of interest happens in your
+  system. For example, it may be helpful to log whenever a user is deleted.
+
+      def delete_user(user) do
+        Logger.info fn ->
+          "Deleting user from the system: #{inspect(user)}"
+        end
+        # ...
+      end
+
+  The `Logger.info/2` macro emits the provided message at the `:info`
+  level. There are additional macros for other levels. Notice the argument
+  passed to `Logger.info` in the above example is a zero argument function.
+
+  Although the Logger macros accept messages as strings as well as functions,
+  it's recommended to use functions whenever the message is expensive to
+  compute. In the example above, the message will be evaluated (and thus the
+  interpolation inside it) whatever the level is, even if the message will not
+  be actually logged at runtime; the only way of avoiding evaluation of such
+  message is purging the log call at compile-time through the
+  `:compile_time_purge_level` option (see below), or using a function that is
+  evaluated to generate the message only if the message needs to be logged
+  according to the runtime level.
+
   ## Levels
 
   The supported levels are:
@@ -88,7 +112,10 @@ defmodule Logger do
       cause the message to be ignored. Keep in mind that each backend
       may have its specific level, too. Note that, unlike what happens with the
       `:compile_time_purge_level` option, the argument passed to `Logger` calls
-      is evaluated even if the level of the call is lower than `:level`.
+      is evaluated even if the level of the call is lower than
+      `:level`. For this reason, messages that are expensive to
+      compute should be wrapped in 0-arity anonymous functions that are
+      evaluated only when the `:label` option demands it.
 
     * `:utc_log` - when `true`, uses UTC in logs. By default it uses
       local time (i.e., it defaults to `false`).