Merge pull request akka#22386 from akka/wip-17895-log-more-args-patriknw

improve docs for logging with more than 4 args, akka#17895

akka-actor/src/main/scala/akka/event/Logging.scala

@@ -1061,6 +1061,9 @@ object Logging {
  * {{{
  * log.error(exception, "Exception while processing {} in state {}", msg, state)
  * }}}
+ *
+ * More than four arguments can be defined by using an `Array` with the method with
+ * one argument parameter.
  */
 trait LoggingAdapter {
 
@@ -1097,6 +1100,9 @@ trait LoggingAdapter {
   def error(cause: Throwable, message: String): Unit = { if (isErrorEnabled) notifyError(cause, message) }
   /**
    * Message template with 1 replacement argument.
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def error(cause: Throwable, template: String, arg1: Any): Unit = { if (isErrorEnabled) notifyError(cause, format1(template, arg1)) }
@@ -1123,6 +1129,9 @@ trait LoggingAdapter {
   def error(message: String): Unit = { if (isErrorEnabled) notifyError(message) }
   /**
    * Message template with 1 replacement argument.
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def error(template: String, arg1: Any): Unit = { if (isErrorEnabled) notifyError(format1(template, arg1)) }
@@ -1149,6 +1158,9 @@ trait LoggingAdapter {
   def warning(message: String): Unit = { if (isWarningEnabled) notifyWarning(message) }
   /**
    * Message template with 1 replacement argument.
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def warning(template: String, arg1: Any): Unit = { if (isWarningEnabled) notifyWarning(format1(template, arg1)) }
@@ -1175,6 +1187,9 @@ trait LoggingAdapter {
   def info(message: String) { if (isInfoEnabled) notifyInfo(message) }
   /**
    * Message template with 1 replacement argument.
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def info(template: String, arg1: Any): Unit = { if (isInfoEnabled) notifyInfo(format1(template, arg1)) }
@@ -1201,6 +1216,9 @@ trait LoggingAdapter {
   def debug(message: String) { if (isDebugEnabled) notifyDebug(message) }
   /**
    * Message template with 1 replacement argument.
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def debug(template: String, arg1: Any): Unit = { if (isDebugEnabled) notifyDebug(format1(template, arg1)) }
@@ -1226,6 +1244,9 @@ trait LoggingAdapter {
   def log(level: Logging.LogLevel, message: String) { if (isEnabled(level)) notifyLog(level, message) }
   /**
    * Message template with 1 replacement argument.
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    */
   def log(level: Logging.LogLevel, template: String, arg1: Any): Unit = { if (isEnabled(level)) notifyLog(level, format1(template, arg1)) }
   /**
@@ -1258,6 +1279,10 @@ trait LoggingAdapter {
     case Logging.DebugLevel   ⇒ if (isDebugEnabled) notifyDebug(message)
   }
 
+  /**
+   * If `arg` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
+   */
   private def format1(t: String, arg: Any): String = arg match {
     case a: Array[_] if !a.getClass.getComponentType.isPrimitive ⇒ format(t, a: _*)
     case a: Array[_] ⇒ format(t, (a map (_.asInstanceOf[AnyRef]): _*))
@@ -1433,10 +1458,13 @@ class MarkerLoggingAdapter(
   /**
    * Message template with 1 replacement argument.
    * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special".
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def error(marker: LogMarker, cause: Throwable, template: String, arg1: Any): Unit =
-    if (isErrorEnabled) bus.publish(Error(logSource, logClass, format(template, arg1), mdc, marker))
+    if (isErrorEnabled) bus.publish(Error(logSource, logClass, format1(template, arg1), mdc, marker))
 
   /**
    * Message template with 2 replacement arguments.
@@ -1473,10 +1501,13 @@ class MarkerLoggingAdapter(
   /**
    * Message template with 1 replacement argument.
    * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special".
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def error(marker: LogMarker, template: String, arg1: Any): Unit =
-    if (isErrorEnabled) bus.publish(Error(logSource, logClass, format(template, arg1), mdc, marker))
+    if (isErrorEnabled) bus.publish(Error(logSource, logClass, format1(template, arg1), mdc, marker))
 
   /**
    * Message template with 2 replacement arguments.
@@ -1513,10 +1544,13 @@ class MarkerLoggingAdapter(
   /**
    * Message template with 1 replacement argument.
    * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special".
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def warning(marker: LogMarker, template: String, arg1: Any): Unit =
-    if (isWarningEnabled) bus.publish(Warning(logSource, logClass, format(template, arg1), mdc, marker))
+    if (isWarningEnabled) bus.publish(Warning(logSource, logClass, format1(template, arg1), mdc, marker))
 
   /**
    * Message template with 2 replacement arguments.
@@ -1553,10 +1587,13 @@ class MarkerLoggingAdapter(
   /**
    * Message template with 1 replacement argument.
    * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special".
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def info(marker: LogMarker, template: String, arg1: Any): Unit =
-    if (isInfoEnabled) bus.publish(Info(logSource, logClass, format(template, arg1), mdc, marker))
+    if (isInfoEnabled) bus.publish(Info(logSource, logClass, format1(template, arg1), mdc, marker))
 
   /**
    * Message template with 2 replacement arguments.
@@ -1593,10 +1630,13 @@ class MarkerLoggingAdapter(
   /**
    * Message template with 1 replacement argument.
    * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special".
+   *
+   * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when
+   * there are more than four arguments.
    * @see [[LoggingAdapter]]
    */
   def debug(marker: LogMarker, template: String, arg1: Any): Unit =
-    if (isDebugEnabled) bus.publish(Debug(logSource, logClass, format(template, arg1), mdc, marker))
+    if (isDebugEnabled) bus.publish(Debug(logSource, logClass, format1(template, arg1), mdc, marker))
 
   /**
    * Message template with 2 replacement arguments.
@@ -1622,6 +1662,12 @@ class MarkerLoggingAdapter(
   def debug(marker: LogMarker, template: String, arg1: Any, arg2: Any, arg3: Any, arg4: Any): Unit =
     if (isDebugEnabled) bus.publish(Debug(logSource, logClass, format(template, arg1, arg2, arg3, arg4), mdc, marker))
 
+  // Copy of LoggingAdapter.format1 due to binary compatibility restrictions
+  private def format1(t: String, arg: Any): String = arg match {
+    case a: Array[_] if !a.getClass.getComponentType.isPrimitive ⇒ format(t, a: _*)
+    case a: Array[_] ⇒ format(t, (a map (_.asInstanceOf[AnyRef]): _*))
+    case x ⇒ format(t, x)
+  }
 }
 
 final class DiagnosticMarkerBusLoggingAdapter(

akka-docs/rst/scala/logging.rst

@@ -40,7 +40,7 @@ The source object is translated to a String according to the following rules:
 The log message may contain argument placeholders ``{}``, which will be
 substituted if the log level is enabled. Giving more arguments as there are
 placeholders results in a warning being appended to the log statement (i.e. on
-the same line with the same severity). You may pass a Java array as the only
+the same line with the same severity). You may pass an array as the only
 substitution argument to have its elements be treated individually:
 
 .. includecode:: code/docs/event/LoggingDocSpec.scala#array