diff --git a/akka-docs/general/index.rst b/akka-docs/general/index.rst index 4853061fbc..945b52a278 100644 --- a/akka-docs/general/index.rst +++ b/akka-docs/general/index.rst @@ -7,6 +7,5 @@ General jmm message-send-semantics configuration - logging addressing supervision diff --git a/akka-docs/general/code/akka/docs/event/LoggingDocTest.scala b/akka-docs/java/code/akka/docs/event/LoggingDocTest.scala similarity index 100% rename from akka-docs/general/code/akka/docs/event/LoggingDocTest.scala rename to akka-docs/java/code/akka/docs/event/LoggingDocTest.scala diff --git a/akka-docs/general/code/akka/docs/event/LoggingDocTestBase.java b/akka-docs/java/code/akka/docs/event/LoggingDocTestBase.java similarity index 100% rename from akka-docs/general/code/akka/docs/event/LoggingDocTestBase.java rename to akka-docs/java/code/akka/docs/event/LoggingDocTestBase.java 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/general/code/akka/docs/event/LoggingDocSpec.scala b/akka-docs/scala/code/akka/docs/event/LoggingDocSpec.scala similarity index 100% rename from akka-docs/general/code/akka/docs/event/LoggingDocSpec.scala rename to akka-docs/scala/code/akka/docs/event/LoggingDocSpec.scala 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/general/logging.rst b/akka-docs/scala/logging.rst similarity index 85% rename from akka-docs/general/logging.rst rename to akka-docs/scala/logging.rst index 50f958db63..e5cc7597a9 100644 --- a/akka-docs/general/logging.rst +++ b/akka-docs/scala/logging.rst @@ -1,8 +1,8 @@ -.. _logging: +.. _logging-scala: -######### - Logging -######### +################# + Logging (Scala) +################# .. sidebar:: Contents @@ -12,7 +12,7 @@ How to Log ========== Create a ``LoggingAdapter`` and use the ``error``, ``warning``, ``info``, or ``debug`` methods, -as illustrated in this example in Scala: +as illustrated in this example: .. includecode:: code/akka/docs/event/LoggingDocSpec.scala :include: my-actor @@ -23,12 +23,7 @@ For convenience you can mixin the ``log`` member into actors, instead of definin class MyActor extends Actor with akka.actor.ActorLogging { -Corresponding example in Java: - -.. includecode:: code/akka/docs/event/LoggingDocTestBase.java - :include: imports,my-actor - -The second parameter to the ``Logging`` or ``Logging.getLogger`` is the source of this logging channel. +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 @@ -54,21 +49,16 @@ Here you can also define the log level. 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` +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 in Scala: +Example of creating a listener: .. includecode:: code/akka/docs/event/LoggingDocSpec.scala :include: my-event-listener -Corresponding example in Java: -.. includecode:: code/akka/docs/event/LoggingDocTestBase.java - :include: imports,imports-listener,my-event-listener - - -.. _slf4j: +.. _slf4j-scala: SLF4J =====