example for Streams log operator (#25283)

* and added all log levels in Attributes for convenient single access point

akka-docs/src/main/paradox/stream/operators/Source-or-Flow/log.md

@@ -29,3 +29,10 @@ This can be changed by calling @scala[`Attributes.logLevels(...)`] @java[`Attrib
 
 @@@
 
+## Example
+
+Scala
+:   @@snip [SourceOrFlow.scala]($code$/scala/docs/stream/operators/SourceOrFlow.scala) { #log }
+
+Java
+:   @@snip [SourceOrFlow.java]($code$/java/jdocs/stream/operators/SourceOrFlow.java) { #log }

akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java

@@ -0,0 +1,27 @@
+/**
+ * Copyright (C) 2018 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators;
+
+import akka.stream.javadsl.Flow;
+
+//#log
+import akka.stream.Attributes;
+
+//#log
+
+class SourceOrFlow {
+
+  void logExample() {
+    Flow.of(String.class)
+      //#log
+      .log("myStream")
+      .addAttributes(Attributes.createLogLevels(
+        Attributes.logLevelOff(), // onElement
+        Attributes.logLevelError(), // onFailure
+        Attributes.logLevelInfo())) // onFinish
+    //#log
+    ;
+  }
+}

akka-docs/src/test/scala/docs/stream/operators/SourceOrFlow.scala

@@ -0,0 +1,29 @@
+/**
+ * Copyright (C) 2018 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators
+
+import akka.stream.scaladsl._
+
+//
+
+object SourceOrFlow {
+
+  def logExample(): Unit = {
+    //#log
+    import akka.stream.Attributes
+
+    //#log
+
+    Flow[String]
+      //#log
+      .log(name = "myStream")
+      .addAttributes(Attributes.logLevels(
+        onElement = Attributes.LogLevels.Off,
+        onFailure = Attributes.LogLevels.Error,
+        onFinish = Attributes.LogLevels.Info))
+    //#log
+  }
+
+}

akka-stream/src/main/scala/akka/stream/Attributes.scala

@@ -294,10 +294,29 @@ object Attributes {
   final case object AsyncBoundary extends Attribute
 
   object LogLevels {
-    /** Use to disable logging on certain operations when configuring [[Attributes.LogLevels]] */
+    /** Use to disable logging on certain operations when configuring [[Attributes#logLevels]] */
     final val Off: Logging.LogLevel = Logging.levelFor("off").get
+    /** Use to enable logging at ERROR level for certain operations when configuring [[Attributes#logLevels]] */
+    final val Error: Logging.LogLevel = Logging.ErrorLevel
+    /** Use to enable logging at WARNING level for certain operations when configuring [[Attributes#logLevels]] */
+    final val Warning: Logging.LogLevel = Logging.WarningLevel
+    /** Use to enable logging at INFO level for certain operations when configuring [[Attributes#logLevels]] */
+    final val Info: Logging.LogLevel = Logging.InfoLevel
+    /** Use to enable logging at DEBUG level for certain operations when configuring [[Attributes#logLevels]] */
+    final val Debug: Logging.LogLevel = Logging.DebugLevel
   }
 
+  /** Java API: Use to disable logging on certain operations when configuring [[Attributes#createLogLevels]] */
+  def logLevelOff: Logging.LogLevel = LogLevels.Off
+  /** Use to enable logging at ERROR level for certain operations when configuring [[Attributes#createLogLevels]] */
+  def logLevelError: Logging.LogLevel = LogLevels.Error
+  /** Use to enable logging at WARNING level for certain operations when configuring [[Attributes#createLogLevels]] */
+  def logLevelWarning: Logging.LogLevel = LogLevels.Warning
+  /** Use to enable logging at INFO level for certain operations when configuring [[Attributes#createLogLevels]] */
+  def logLevelInfo: Logging.LogLevel = LogLevels.Info
+  /** Use to enable logging at DEBUG level for certain operations when configuring [[Attributes#createLogLevels]] */
+  def logLevelDebug: Logging.LogLevel = LogLevels.Debug
+
   /**
    * INTERNAL API
    */
@@ -342,7 +361,7 @@ object Attributes {
 
   /**
    * Configures `log()` operator log-levels to be used when logging.
-   * Logging a certain operation can be completely disabled by using [[LogLevels.Off]].
+   * Logging a certain operation can be completely disabled by using [[Attributes#logLevelOff]].
    *
    * See [[Attributes.createLogLevels]] for Java API
    */