diff --git a/akka-actor-testkit-typed/src/test/resources/logback-test.xml b/akka-actor-testkit-typed/src/test/resources/logback-test.xml index db91164e39..edb5c316e3 100644 --- a/akka-actor-testkit-typed/src/test/resources/logback-test.xml +++ b/akka-actor-testkit-typed/src/test/resources/logback-test.xml @@ -8,7 +8,7 @@ INFO - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-actor-typed-tests/src/test/resources/logback-doc-dev.xml b/akka-actor-typed-tests/src/test/resources/logback-doc-dev.xml index 9c00c6edea..b68fc6576a 100644 --- a/akka-actor-typed-tests/src/test/resources/logback-doc-dev.xml +++ b/akka-actor-typed-tests/src/test/resources/logback-doc-dev.xml @@ -6,14 +6,14 @@ INFO - [%date{ISO8601}] [%level] [%logger] [%thread] [%X{akkaSource}] - %msg%n + [%date{ISO8601}] [%level] [%logger] [%marker] [%thread] - %msg {%mdc}%n target/myapp-dev.log - [%date{ISO8601}] [%level] [%logger] [%thread] [%X{akkaSource}] - %msg%n + [%date{ISO8601}] [%level] [%logger] [%marker] [%thread] - %msg {%mdc}%n diff --git a/akka-actor-typed-tests/src/test/resources/logback-doc-prod.xml b/akka-actor-typed-tests/src/test/resources/logback-doc-prod.xml index 882b724863..3977793dd5 100644 --- a/akka-actor-typed-tests/src/test/resources/logback-doc-prod.xml +++ b/akka-actor-typed-tests/src/test/resources/logback-doc-prod.xml @@ -8,7 +8,7 @@ myapp_%d{yyyy-MM-dd}.log - [%date{ISO8601}] [%level] [%logger] [%thread] [%X{akkaSource}] - %msg%n + [%date{ISO8601}] [%level] [%logger] [%marker] [%thread] - %msg {%mdc}%n diff --git a/akka-actor-typed-tests/src/test/resources/logback-doc-test.xml b/akka-actor-typed-tests/src/test/resources/logback-doc-test.xml index d33c48e8a6..7c37e5d414 100644 --- a/akka-actor-typed-tests/src/test/resources/logback-doc-test.xml +++ b/akka-actor-typed-tests/src/test/resources/logback-doc-test.xml @@ -6,7 +6,7 @@ INFO - [%date{ISO8601}] [%level] [%logger] [%thread] [%X{akkaSource}] - %msg%n + [%date{ISO8601}] [%level] [%logger] [%marker] [%thread] - %msg {%mdc}%n diff --git a/akka-actor-typed-tests/src/test/resources/logback-test.xml b/akka-actor-typed-tests/src/test/resources/logback-test.xml index d492d46ed9..068d2bc81c 100644 --- a/akka-actor-typed-tests/src/test/resources/logback-test.xml +++ b/akka-actor-typed-tests/src/test/resources/logback-test.xml @@ -8,7 +8,7 @@ INFO - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-bench-jmh/src/main/resources/logback-test.xml b/akka-bench-jmh/src/main/resources/logback-test.xml index ab25b19f2e..84ff1fe425 100644 --- a/akka-bench-jmh/src/main/resources/logback-test.xml +++ b/akka-bench-jmh/src/main/resources/logback-test.xml @@ -8,7 +8,7 @@ INFO - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-cluster-metrics/src/test/resources/logback-test.xml b/akka-cluster-metrics/src/test/resources/logback-test.xml index 997c781a0c..1e665afb96 100644 --- a/akka-cluster-metrics/src/test/resources/logback-test.xml +++ b/akka-cluster-metrics/src/test/resources/logback-test.xml @@ -3,7 +3,7 @@ - + diff --git a/akka-cluster-sharding-typed/src/multi-jvm/resources/logback-test.xml b/akka-cluster-sharding-typed/src/multi-jvm/resources/logback-test.xml index b8aaf237b2..e2d3457e51 100644 --- a/akka-cluster-sharding-typed/src/multi-jvm/resources/logback-test.xml +++ b/akka-cluster-sharding-typed/src/multi-jvm/resources/logback-test.xml @@ -5,7 +5,7 @@ - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-cluster-sharding-typed/src/test/resources/logback-test.xml b/akka-cluster-sharding-typed/src/test/resources/logback-test.xml index 254c2d1af2..41ea808109 100644 --- a/akka-cluster-sharding-typed/src/test/resources/logback-test.xml +++ b/akka-cluster-sharding-typed/src/test/resources/logback-test.xml @@ -8,7 +8,7 @@ INFO - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} { "persistenceId": "%X{persistenceId}", "persistencePhase": "%X{persistencePhase}" } - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-cluster-typed/src/multi-jvm/resources/logback-test.xml b/akka-cluster-typed/src/multi-jvm/resources/logback-test.xml index b8aaf237b2..e2d3457e51 100644 --- a/akka-cluster-typed/src/multi-jvm/resources/logback-test.xml +++ b/akka-cluster-typed/src/multi-jvm/resources/logback-test.xml @@ -5,7 +5,7 @@ - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-cluster-typed/src/test/resources/logback-test.xml b/akka-cluster-typed/src/test/resources/logback-test.xml index 7c037e2347..41ea808109 100644 --- a/akka-cluster-typed/src/test/resources/logback-test.xml +++ b/akka-cluster-typed/src/test/resources/logback-test.xml @@ -8,7 +8,7 @@ INFO - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-docs/src/main/paradox/logging.md b/akka-docs/src/main/paradox/logging.md index 60aeb251ef..9d641752b8 100644 --- a/akka-docs/src/main/paradox/logging.md +++ b/akka-docs/src/main/paradox/logging.md @@ -394,8 +394,8 @@ val log = Logging(system.eventStream, "my.nice.string") Java : ```java - final LoggingAdapter log = Logging.getLogger(system.eventStream(), "my.string"); - ``` +final LoggingAdapter log = Logging.getLogger(system.eventStream(), "my.string"); +``` ### Using the SLF4J API directly @@ -430,19 +430,27 @@ in this example: Place the `logback.xml` file in `src/main/resources/logback.xml`. For tests you can define different logging configuration in `src/test/resources/logback-test.xml`. +MDC properties can be included in the Logback output with for example `%X{akkaSource}` specifier within the +[pattern layout configuration](http://logback.qos.ch/manual/layouts.html#mdc): + +``` + + %date{ISO8601} %-5level %logger{36} %X{akkaSource} - %msg%n + +``` + +All MDC properties as key-value entries can be included with `%mdc`: + +``` + + %date{ISO8601} %-5level %logger{36} - %msg {%mdc}%n + +``` + ### Logging Thread, Akka Source and Actor System 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 - - -``` @@@ note @@ -455,26 +463,12 @@ available in the logs. Another helpful facility is that Akka captures the actor’s address when instantiating a logger within it, meaning that the full instance identification is available for associating log messages e.g. with members of a router. This -information is available in the MDC with attribute name `akkaSource`: +information is available in the MDC with attribute name `akkaSource`. -``` - - - %date{ISO8601} %-5level %logger{36} %X{akkaSource} - %msg%n - - -``` +The address of the actor system, containing host and port if the system is using cluster, is available through `akkaAddress`. Finally, the actor system in which the logging was performed -is available in the MDC with attribute name `sourceActorSystem`: - -``` - - - %date{ISO8601} %-5level %logger{36} %X{sourceActorSystem} - %msg%n - - -``` +is available in the MDC with attribute name `sourceActorSystem`. For more details on what this attribute contains—also for non-actors—please see [How to Log](#how-to-log). @@ -483,15 +477,7 @@ For more details on what this attribute contains—also for non-actors—please Akka's logging is asynchronous which means that the timestamp of a log entry is taken from when the underlying logger implementation is called, which can be surprising at first. -If you want to more accurately output the timestamp, use the MDC attribute `akkaTimestamp`: - -``` - - - %X{akkaTimestamp} %-5level %logger{36} %X{akkaTimestamp} - %msg%n - - -``` +If you want to more accurately output the timestamp, use the MDC attribute `akkaTimestamp`. ### MDC values defined by the application @@ -508,9 +494,9 @@ val log: DiagnosticLoggingAdapter = Logging(this); Java : ```java - // Within your AbstractActor - final DiagnosticLoggingAdapter log = Logging.getLogger(this); - ``` +// Within your AbstractActor +final DiagnosticLoggingAdapter log = Logging.getLogger(this); +``` Once you have the logger, you need to add the custom values before you log something. This way, the values will be put in the SLF4J MDC right before appending the log and removed after. @@ -552,6 +538,14 @@ Now, the values will be available in the MDC, so you can use them in the layout ``` +All MDC properties as key-value entries can be included with `%mdc`: + +``` + + %date{ISO8601} %-5level %logger{36} - %msg {%mdc}%n + +``` + ### Using Markers Some logging libraries allow, in addition to MDC data, attaching so called "markers" to log statements. @@ -563,17 +557,6 @@ Markers are available through the LoggingAdapters, when obtained via `Logging.wi The first argument passed into all log calls then should be a `akka.event.LogMarker`. The slf4j bridge provided by Akka in `akka-slf4j` will automatically pick up this marker value and make it available to SLF4J. -For example you could use it like this: - -``` -%date{ISO8601} [%marker][%level] [%msg]%n -``` - -A more advanced (including most Akka added information) example pattern would be: - -``` -%date{ISO8601} level=[%level] marker=[%marker] logger=[%logger] akkaSource=[%X{akkaSource}] sourceActorSystem=[%X{sourceActorSystem}] sourceThread=[%X{sourceThread}] mdc=[ticket-#%X{ticketNumber}: %X{ticketDesc}] - msg=[%msg]%n----%n -``` Akka is logging some events with markers. Some of these events also include structured MDC properties. @@ -583,6 +566,16 @@ Akka is logging some events with markers. Some of these events also include stru * Akka Remoting is using the markers defined in @apidoc[akka.remote.RemoteLogMarker]. * Akka Cluster Sharding is using the markers defined in @apidoc[akka.cluster.sharding.ShardingLogMarker]. +Markers and MDC properties are automatically picked up by the [Logstash Logback encoder](https://github.com/logstash/logstash-logback-encoder). + +The marker can be included in the Logback output with `%marker` and all MDC properties as key-value entries with `%mdc`. + +``` + + [%date{ISO8601}] [%level] [%logger] [%marker] [%thread] - %msg {%mdc}%n + +``` + #### Using SLF4J's Markers It is also possible to use the `org.slf4j.Marker` with the `LoggingAdapter` when using slf4j. diff --git a/akka-docs/src/main/paradox/typed/logging.md b/akka-docs/src/main/paradox/typed/logging.md index d9090b373b..97cd5494d5 100644 --- a/akka-docs/src/main/paradox/typed/logging.md +++ b/akka-docs/src/main/paradox/typed/logging.md @@ -221,10 +221,15 @@ logging configuration in `src/test/resources/logback-test.xml`. #### MDC values When logging via the @scala[`log`]@java[`getLog`] of the `ActorContext` as described in -@ref:[How to log](#how-to-log) Akka captures the actor's path and includes that in MDC with -attribute name `akkaSource`. +@ref:[How to log](#how-to-log) Akka includes a few MDC properties: -This can be included in the log output with `%X{akkaSource}` specifier within the pattern layout configuration: +* `akkaSource`: the actor's path +* `akkaAddress`: the full address of the ActorSystem, including hostname and port if Cluster is enabled +* `akkaTags`: tags defined in the `Props` of the actor +* `sourceActorSystem`: the name of the ActorSystem + +These MDC properties can be included in the Logback output with for example `%X{akkaSource}` specifier within the +[pattern layout configuration](http://logback.qos.ch/manual/layouts.html#mdc): ``` @@ -232,6 +237,15 @@ This can be included in the log output with `%X{akkaSource}` specifier within th ``` +All MDC properties as key-value entries can be included with `%mdc`: + +``` + + %date{ISO8601} %-5level %logger{36} - %msg {%mdc}%n + +``` + + ## Internal logging by Akka ### Event bus @@ -385,51 +399,34 @@ akka.remote.artery { Since the logging is done asynchronously the thread in which the logging was performed is captured in 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 - -``` - -The path of the actor in which the logging was performed is available in the MDC with attribute name `akkaSource`, -With Logback the actor path is available with `%X{akkaSource}` specifier within the pattern layout configuration: -``` - - %date{ISO8601} %-5level %logger{36} %X{akkaSource} - %msg%n - -``` +The path of the actor in which the logging was performed is available in the MDC with attribute name `akkaSource`. The actor system name in which the logging was performed is available in the MDC with attribute name `sourceActorSystem`, but that is typically also included in the `akkaSource` attribute. -With Logback the ActorSystem name is available with `%X{sourceActorSystem}` specifier within the pattern layout configuration: - -``` - - %date{ISO8601} %-5level %logger{36} %X{sourceActorSystem} - %msg%n - -``` - -The address of the actor system, containing host and port if the system is using cluster, is available through `akkaAddress`: - -``` - - %date{ISO8601} %-5level %logger{36} %X{akkaAddress} - %msg%n - -``` +The address of the actor system, containing host and port if the system is using cluster, is available through `akkaAddress`. For typed actors the log event timestamp is taken when the log call was made but for Akka's _internal_ logging as well as the classic actor logging is asynchronous which means that the timestamp of a log entry is taken from when the underlying logger implementation is called, which can be surprising at first. If you want to more accurately output the timestamp for such loggers, use the MDC attribute `akkaTimestamp`. Note that the MDC key will not have any value for a typed actor. -With Logback the timestamp is available with `%X{akkaTimestamp}` specifier within the pattern layout configuration: + +These MDC properties can be included in the Logback output with for example `%X{akkaSource}` specifier within the +[pattern layout configuration](http://logback.qos.ch/manual/layouts.html#mdc): ``` - %X{akkaTimestamp} %-5level %logger{36} %X{akkaTimestamp} - %msg%n + %date{ISO8601} %-5level %logger{36} %X{akkaSource} - %msg%n + +``` + +All MDC properties as key-value entries can be included with `%mdc`: + +``` + + %date{ISO8601} %-5level %logger{36} - %msg {%mdc}%n ``` @@ -443,6 +440,16 @@ Akka is logging some events with markers. Some of these events also include stru * Akka Remoting is using the markers defined in @apidoc[akka.remote.RemoteLogMarker]. * Akka Cluster Sharding is using the markers defined in @apidoc[akka.cluster.sharding.ShardingLogMarker]. +Markers and MDC properties are automatically picked up by the [Logstash Logback encoder](https://github.com/logstash/logstash-logback-encoder). + +The marker can be included in the Logback output with `%marker` and all MDC properties as key-value entries with `%mdc`. + +``` + + [%date{ISO8601}] [%level] [%logger] [%marker] [%thread] - %msg {%mdc}%n + +``` + ### Logger names It can be useful to enable debug level or other SLF4J backend configuration for certain modules of Akka when diff --git a/akka-docs/src/test/resources/logback-test.xml b/akka-docs/src/test/resources/logback-test.xml index f877ccdf75..5e0b801edc 100644 --- a/akka-docs/src/test/resources/logback-test.xml +++ b/akka-docs/src/test/resources/logback-test.xml @@ -8,7 +8,7 @@ INFO - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-osgi/src/test/resources/logback-test.xml b/akka-osgi/src/test/resources/logback-test.xml index 9c441a6fb6..b932a3d8f8 100644 --- a/akka-osgi/src/test/resources/logback-test.xml +++ b/akka-osgi/src/test/resources/logback-test.xml @@ -4,7 +4,7 @@ - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n @@ -12,7 +12,7 @@ target/akka-osgi.log true - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-persistence-typed/src/test/resources/logback-test.xml b/akka-persistence-typed/src/test/resources/logback-test.xml index 254c2d1af2..41ea808109 100644 --- a/akka-persistence-typed/src/test/resources/logback-test.xml +++ b/akka-persistence-typed/src/test/resources/logback-test.xml @@ -8,7 +8,7 @@ INFO - %date{ISO8601} %-5level %logger %X{akkaSource} %X{sourceThread} { "persistenceId": "%X{persistenceId}", "persistencePhase": "%X{persistencePhase}" } - %msg%n + %date{ISO8601} %-5level %logger %marker - %msg {%mdc}%n diff --git a/akka-slf4j/src/test/resources/logback-test.xml b/akka-slf4j/src/test/resources/logback-test.xml index f3847c005a..7eec3dd3ca 100644 --- a/akka-slf4j/src/test/resources/logback-test.xml +++ b/akka-slf4j/src/test/resources/logback-test.xml @@ -7,7 +7,7 @@ - %date{ISO8601} level=[%level] marker=[%marker] logger=[%logger] akkaSource=[%X{akkaSource}] akkaAddress=[%X{akkaAddress}] sourceActorSystem=[%X{sourceActorSystem}] sourceThread=[%X{sourceThread}] mdc=[ticket-#%X{ticketNumber}: %X{ticketDesc} p1: %X{p1} p2: %X{p2}] - msg=[%msg]%n----%n + %date{ISO8601} level=[%level] marker=[%marker] logger=[%logger] mdc=[%mdc] - msg=[%msg]%n----%n