diff --git a/akka-actor/src/main/scala/akka/event/Logging.scala b/akka-actor/src/main/scala/akka/event/Logging.scala index d6e71aa586..0425b4c661 100644 --- a/akka-actor/src/main/scala/akka/event/Logging.scala +++ b/akka-actor/src/main/scala/akka/event/Logging.scala @@ -281,19 +281,34 @@ object Logging { val debugFormat = "[DEBUG] [%s] [%s] [%s] %s".intern /** - * Obtain LoggingAdapter for the given application and source object. The - * source is used to identify the source of this logging channel and must have + * Obtain LoggingAdapter for the given event stream (system) and source object. + * Note that there is an implicit conversion from [[akka.actor.ActorSystem]] + * to [[akka.event.LoggingBus]]. + * + * The source is used to identify the source of this logging channel and must have * a corresponding LogSource[T] instance in scope; by default these are - * provided for Class[_], Actor, ActorRef and String types. + * provided for Class[_], Actor, ActorRef and String types. The source + * object is translated to a String according to the following rules: + * */ def apply[T: LogSource](eventStream: LoggingBus, logSource: T): LoggingAdapter = new BusLogging(eventStream, implicitly[LogSource[T]].genString(logSource)) /** - * Java API: Obtain LoggingAdapter for the given application and source object. The - * source object is used to identify the source of this logging channel; if it is - * an Actor or ActorRef, its address is used, in case of a class an approximation of - * its simpleName and in all other cases the simpleName of its class. + * Java API: Obtain LoggingAdapter for the given system and source object. The + * source object is used to identify the source of this logging channel. The source + * object is translated to a String according to the following rules: + * */ def getLogger(system: ActorSystem, logSource: AnyRef): LoggingAdapter = apply(system.eventStream, LogSource.fromAnyRef(logSource)) @@ -354,6 +369,11 @@ object Logging { */ case object LoggerInitialized + /** + * Java API to create a LoggerInitialized message. + */ + def loggerInitialized() = LoggerInitialized + class LoggerInitializationException(msg: String) extends AkkaException(msg) trait StdOutLogger { diff --git a/akka-docs/general/code/ConfigDocSpec.scala b/akka-docs/general/code/akka/docs/config/ConfigDocSpec.scala similarity index 100% rename from akka-docs/general/code/ConfigDocSpec.scala rename to akka-docs/general/code/akka/docs/config/ConfigDocSpec.scala diff --git a/akka-docs/general/configuration.rst b/akka-docs/general/configuration.rst index 9328e19561..96467312bd 100644 --- a/akka-docs/general/configuration.rst +++ b/akka-docs/general/configuration.rst @@ -47,7 +47,7 @@ with ``/``. ``-Dconfig.resource=/dev.conf`` will load the ``dev.conf`` from the You may also specify and parse the configuration programmatically in other ways when instantiating the ``ActorSystem``. -.. includecode:: code/ConfigDocSpec.scala +.. includecode:: code/akka/docs/config/ConfigDocSpec.scala :include: imports,custom-config The ``ConfigFactory`` provides several methods to parse the configuration from various sources. diff --git a/akka-docs/general/event-handler.rst b/akka-docs/general/event-handler.rst deleted file mode 100644 index e6aa422b37..0000000000 --- a/akka-docs/general/event-handler.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. _event-handler: - -Event Handler -============= - -There is an Event Handler which takes the place of a logging system in Akka: - -.. code-block:: scala - - akka.event.EventHandler - -You can configure which event handlers should be registered at boot time. That is done using the 'event-handlers' element in -the :ref:`configuration`. Here you can also define the log level. - -.. code-block:: ruby - - akka { - # event handlers to register at boot time (EventHandler$DefaultListener logs to STDOUT) - event-handlers = ["akka.event.EventHandler$DefaultListener"] - loglevel = "DEBUG" # Options: ERROR, WARNING, INFO, DEBUG - } - -The default one logs to STDOUT and is registered by default. It is not intended to be used for production. There is also an :ref:`slf4j` event handler available in the 'akka-slf4j' module. - -Example of creating a listener from Scala (from Java you just have to create an 'UntypedActor' and create a handler for these messages): - -.. code-block:: scala - - val errorHandlerEventListener = Actor.actorOf(new Actor { - self.dispatcher = EventHandler.EventHandlerDispatcher - - def receive = { - case EventHandler.Error(cause, instance, message) => ... - case EventHandler.Warning(instance, message) => ... - case EventHandler.Info(instance, message) => ... - case EventHandler.Debug(instance, message) => ... - case genericEvent => ... - } - }) - -To add the listener: - -.. code-block:: scala - - EventHandler.addListener(errorHandlerEventListener) - -To remove the listener: - -.. code-block:: scala - - EventHandler.removeListener(errorHandlerEventListener) - -To log an event: - -.. code-block:: scala - - EventHandler.notify(EventHandler.Error(exception, this, message)) - - EventHandler.notify(EventHandler.Warning(this, message)) - - EventHandler.notify(EventHandler.Info(this, message)) - - EventHandler.notify(EventHandler.Debug(this, message)) - - EventHandler.notify(object) - -You can also use one of the direct methods (for a bit better performance): - -.. code-block:: scala - - EventHandler.error(exception, this, message) - - EventHandler.error(this, message) - - EventHandler.warning(this, message) - - EventHandler.info(this, message) - - EventHandler.debug(this, message) - -The event handler allows you to send an arbitrary object to the handler which you can handle in your event handler listener. The default listener prints it's toString String out to STDOUT. - -.. code-block:: scala - - EventHandler.notify(anyRef) - -The methods take a call-by-name parameter for the message to avoid object allocation and execution if level is disabled. The following formatting function will not be evaluated if level is INFO, WARNING, or ERROR. - -.. code-block:: scala - - EventHandler.debug(this, "Processing took %s ms".format(duration)) - -From Java you need to nest the call in an if statement to achieve the same thing. - -.. code-block:: java - - if (EventHandler.isDebugEnabled()) { - EventHandler.debug(this, String.format("Processing took %s ms", duration)); - } - - diff --git a/akka-docs/general/index.rst b/akka-docs/general/index.rst index f3cc0d2a7d..945b52a278 100644 --- a/akka-docs/general/index.rst +++ b/akka-docs/general/index.rst @@ -7,7 +7,5 @@ General jmm message-send-semantics configuration - event-handler - slf4j addressing supervision diff --git a/akka-docs/general/slf4j.rst b/akka-docs/general/slf4j.rst deleted file mode 100644 index 296cbb7b48..0000000000 --- a/akka-docs/general/slf4j.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _slf4j: - -SLF4J -===== - -This module is available in the 'akka-slf4j.jar'. It has one single dependency; the slf4j-api jar. In runtime you -also need a SLF4J backend, we recommend `Logback `_: - - .. code-block:: scala - - lazy val logback = "ch.qos.logback" % "logback-classic" % "1.0.0" % "runtime" - - -Event Handler -------------- - -This module includes a SLF4J Event Handler that works with Akka's standard Event Handler. You enabled it in the 'event-handlers' element in -the :ref:`configuration`. Here you can also define the log level. - -.. code-block:: ruby - - akka { - event-handlers = ["akka.event.slf4j.Slf4jEventHandler"] - loglevel = "DEBUG" - } - -Read more about how to use the :ref:`event-handler`. - -Logging thread in MDC ---------------------- - -Since the logging is done asynchronously the thread in which the logging was performed is captured in -Mapped Diagnostic Context (MDC) with attribute name ``sourceThread``. -With Logback the thread name is available with ``%X{sourceThread}`` specifier within the pattern layout configuration:: - - - - %date{ISO8601} %-5level %logger{36} %X{sourceThread} - %msg%n - - - - \ No newline at end of file diff --git a/akka-docs/java/code/akka/docs/event/LoggingDocTest.scala b/akka-docs/java/code/akka/docs/event/LoggingDocTest.scala new file mode 100644 index 0000000000..2a55bdb81a --- /dev/null +++ b/akka-docs/java/code/akka/docs/event/LoggingDocTest.scala @@ -0,0 +1,5 @@ +package akka.docs.event + +import org.scalatest.junit.JUnitSuite + +class LoggingDocTest extends LoggingDocTestBase with JUnitSuite diff --git a/akka-docs/java/code/akka/docs/event/LoggingDocTestBase.java b/akka-docs/java/code/akka/docs/event/LoggingDocTestBase.java new file mode 100644 index 0000000000..669caa14b1 --- /dev/null +++ b/akka-docs/java/code/akka/docs/event/LoggingDocTestBase.java @@ -0,0 +1,86 @@ +package akka.docs.event; + +//#imports +import akka.event.Logging; +import akka.event.LoggingAdapter; + +//#imports + +//#imports-listener +import akka.event.Logging.InitializeLogger; +import akka.event.Logging.Error; +import akka.event.Logging.Warning; +import akka.event.Logging.Info; +import akka.event.Logging.Debug; + +//#imports-listener + +import org.junit.Test; + +import scala.Option; +import static org.junit.Assert.*; + +import akka.actor.ActorSystem; +import akka.actor.ActorRef; +import akka.actor.UntypedActor; +import akka.actor.UntypedActorFactory; + +public class LoggingDocTestBase { + + @Test + public void useLoggingActor() { + ActorSystem system = ActorSystem.create("MySystem"); + ActorRef myActor = system.actorOf(new UntypedActorFactory() { + public UntypedActor create() { + return new MyActor(); + } + }); + myActor.tell("test"); + system.stop(); + } + + //#my-actor + class MyActor extends UntypedActor { + LoggingAdapter log = Logging.getLogger(getContext().system(), this); + + @Override + public void preStart() { + log.debug("Starting"); + } + + @Override + public void preRestart(Throwable reason, Option message) { + log.error(reason, "Restarting due to [{}] when processing [{}]", reason.getMessage(), + message.isDefined() ? message.get() : ""); + } + + public void onReceive(Object message) { + if (message.equals("test")) { + log.info("Received test"); + } else { + log.warning("Received unknown message: {}", message); + } + } + } + + //#my-actor + + //#my-event-listener + class MyEventListener extends UntypedActor { + public void onReceive(Object message) { + if (message instanceof InitializeLogger) { + getSender().tell(Logging.loggerInitialized()); + } else if (message instanceof Error) { + // ... + } else if (message instanceof Warning) { + // ... + } else if (message instanceof Info) { + // ... + } else if (message instanceof Debug) { + // ... + } + } + } + //#my-event-listener + +} diff --git a/akka-docs/java/index.rst b/akka-docs/java/index.rst index 2ff3d0252e..b7db493c09 100644 --- a/akka-docs/java/index.rst +++ b/akka-docs/java/index.rst @@ -8,6 +8,7 @@ Java API untyped-actors typed-actors + logging futures dataflow stm diff --git a/akka-docs/java/logging.rst b/akka-docs/java/logging.rst new file mode 100644 index 0000000000..c9ad9256fc --- /dev/null +++ b/akka-docs/java/logging.rst @@ -0,0 +1,97 @@ +.. _logging-java: + +################ + Logging (Java) +################ + +.. sidebar:: Contents + + .. contents:: :local: + +How to Log +========== + +Create a ``LoggingAdapter`` and use the ``error``, ``warning``, ``info``, or ``debug`` methods, +as illustrated in this example: + +.. includecode:: code/akka/docs/event/LoggingDocTestBase.java + :include: imports,my-actor + +The second parameter to the ``Logging.getLogger`` is the source of this logging channel. +The source object is translated to a String according to the following rules: + + * if it is an Actor or ActorRef, its path is used + * in case of a String it is used as is + * in case of a class an approximation of its simpleName + * and in all other cases the simpleName of its class + +The log message may contain argument placeholders ``{}``, which will be substituted if the log level +is enabled. + +Event Handler +============= + +Logging is performed asynchronously through an event bus. You can configure which event handlers that should +subscribe to the logging events. That is done using the 'event-handlers' element in the :ref:`configuration`. +Here you can also define the log level. + +.. code-block:: ruby + + akka { + # Event handlers to register at boot time (Logging$DefaultLogger logs to STDOUT) + event-handlers = ["akka.event.Logging$DefaultLogger"] + loglevel = "DEBUG" # Options: ERROR, WARNING, INFO, DEBUG + } + +The default one logs to STDOUT and is registered by default. It is not intended to be used for production. There is also an :ref:`slf4j-java` +event handler available in the 'akka-slf4j' module. + +Example of creating a listener: + +.. includecode:: code/akka/docs/event/LoggingDocTestBase.java + :include: imports,imports-listener,my-event-listener + + +.. _slf4j-java: + +SLF4J +===== + +Akka provides an event handler for `SL4FJ `_. This module is available in the 'akka-slf4j.jar'. +It has one single dependency; the slf4j-api jar. In runtime you also need a SLF4J backend, we recommend `Logback `_: + + .. code-block:: xml + + + ch.qos.logback + logback-classic + 1.0.0 + runtime + + +You need to enable the Slf4jEventHandler in the 'event-handlers' element in +the :ref:`configuration`. Here you can also define the log level of the event bus. +More fine grained log levels can be defined in the configuration of the SLF4J backend +(e.g. logback.xml). The String representation of the source object that is used when +creating the ``LoggingAdapter`` correspond to the name of the SL4FJ logger. + +.. code-block:: ruby + + akka { + event-handlers = ["akka.event.slf4j.Slf4jEventHandler"] + loglevel = "DEBUG" + } + +Logging thread in MDC +--------------------- + +Since the logging is done asynchronously the thread in which the logging was performed is captured in +Mapped Diagnostic Context (MDC) with attribute name ``sourceThread``. +With Logback the thread name is available with ``%X{sourceThread}`` specifier within the pattern layout configuration:: + + + + %date{ISO8601} %-5level %logger{36} %X{sourceThread} - %msg%n + + + diff --git a/akka-docs/scala/code/akka/docs/event/LoggingDocSpec.scala b/akka-docs/scala/code/akka/docs/event/LoggingDocSpec.scala new file mode 100644 index 0000000000..3d355bccb2 --- /dev/null +++ b/akka-docs/scala/code/akka/docs/event/LoggingDocSpec.scala @@ -0,0 +1,59 @@ +package akka.docs.event + +import akka.actor.ActorSystem +import akka.testkit.AkkaSpec +import akka.actor.Actor +import akka.actor.Props + +object LoggingDocSpec { + + //#my-actor + import akka.event.Logging + + class MyActor extends Actor { + val log = Logging(context.system, this) + override def preStart() = { + log.debug("Starting") + } + override def preRestart(reason: Throwable, message: Option[Any]) { + log.error(reason, "Restarting due to [{}] when processing [{}]", + reason.getMessage, message.getOrElse("")) + } + def receive = { + case "test" ⇒ log.info("Received test") + case x ⇒ log.warning("Received unknown message: {}", x) + } + } + //#my-actor + + //#my-event-listener + import akka.event.Logging.InitializeLogger + import akka.event.Logging.LoggerInitialized + import akka.event.Logging.Error + import akka.event.Logging.Warning + import akka.event.Logging.Info + import akka.event.Logging.Debug + + class MyEventListener extends Actor { + def receive = { + case InitializeLogger(_) ⇒ sender ! LoggerInitialized + case Error(cause, logSource, message) ⇒ // ... + case Warning(logSource, message) ⇒ // ... + case Info(logSource, message) ⇒ // ... + case Debug(logSource, message) ⇒ // ... + } + } + //#my-event-listener + +} + +class LoggingDocSpec extends AkkaSpec { + + import LoggingDocSpec.MyActor + + "use a logging actor" in { + val myActor = system.actorOf(Props(new MyActor)) + myActor ! "test" + } + +} diff --git a/akka-docs/scala/index.rst b/akka-docs/scala/index.rst index e4f7e838fe..7e24497f5f 100644 --- a/akka-docs/scala/index.rst +++ b/akka-docs/scala/index.rst @@ -8,6 +8,7 @@ Scala API actors typed-actors + logging futures dataflow agents diff --git a/akka-docs/scala/logging.rst b/akka-docs/scala/logging.rst new file mode 100644 index 0000000000..e5cc7597a9 --- /dev/null +++ b/akka-docs/scala/logging.rst @@ -0,0 +1,99 @@ +.. _logging-scala: + +################# + Logging (Scala) +################# + +.. sidebar:: Contents + + .. contents:: :local: + +How to Log +========== + +Create a ``LoggingAdapter`` and use the ``error``, ``warning``, ``info``, or ``debug`` methods, +as illustrated in this example: + +.. includecode:: code/akka/docs/event/LoggingDocSpec.scala + :include: my-actor + +For convenience you can mixin the ``log`` member into actors, instead of defining it as above. + +.. code-block:: scala + + class MyActor extends Actor with akka.actor.ActorLogging { + +The second parameter to the ``Logging`` is the source of this logging channel. +The source object is translated to a String according to the following rules: + + * if it is an Actor or ActorRef, its path is used + * in case of a String it is used as is + * in case of a class an approximation of its simpleName + * and in all other cases the simpleName of its class + +The log message may contain argument placeholders ``{}``, which will be substituted if the log level +is enabled. + +Event Handler +============= + +Logging is performed asynchronously through an event bus. You can configure which event handlers that should +subscribe to the logging events. That is done using the 'event-handlers' element in the :ref:`configuration`. +Here you can also define the log level. + +.. code-block:: ruby + + akka { + # Event handlers to register at boot time (Logging$DefaultLogger logs to STDOUT) + event-handlers = ["akka.event.Logging$DefaultLogger"] + loglevel = "DEBUG" # Options: ERROR, WARNING, INFO, DEBUG + } + +The default one logs to STDOUT and is registered by default. It is not intended to be used for production. There is also an :ref:`slf4j-scala` +event handler available in the 'akka-slf4j' module. + +Example of creating a listener: + +.. includecode:: code/akka/docs/event/LoggingDocSpec.scala + :include: my-event-listener + + +.. _slf4j-scala: + +SLF4J +===== + +Akka provides an event handler for `SL4FJ `_. This module is available in the 'akka-slf4j.jar'. +It has one single dependency; the slf4j-api jar. In runtime you also need a SLF4J backend, we recommend `Logback `_: + + .. code-block:: scala + + lazy val logback = "ch.qos.logback" % "logback-classic" % "1.0.0" % "runtime" + + +You need to enable the Slf4jEventHandler in the 'event-handlers' element in +the :ref:`configuration`. Here you can also define the log level of the event bus. +More fine grained log levels can be defined in the configuration of the SLF4J backend +(e.g. logback.xml). The String representation of the source object that is used when +creating the ``LoggingAdapter`` correspond to the name of the SL4FJ logger. + +.. code-block:: ruby + + akka { + event-handlers = ["akka.event.slf4j.Slf4jEventHandler"] + loglevel = "DEBUG" + } + +Logging thread in MDC +--------------------- + +Since the logging is done asynchronously the thread in which the logging was performed is captured in +Mapped Diagnostic Context (MDC) with attribute name ``sourceThread``. +With Logback the thread name is available with ``%X{sourceThread}`` specifier within the pattern layout configuration:: + + + + %date{ISO8601} %-5level %logger{36} %X{sourceThread} - %msg%n + + +