raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

Improved utilities/logging documentation

Browse source 
Added some punctuation to improve readability. Also removed some duplicate lines.
This commit is contained in:
Manish Bansal 2020-04-28 12:56:55 +05:30 • committed by GitHub
parent 404d45ea82
commit 87964ed4c7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 7 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

31
akka-docs/src/main/paradox/typed/logging.md
View file

@ -51,7 +51,7 @@ can be a `String` or a `Class`, where the latter is convenience for the class na
When logging via the `ActorContext` the path of the actor will automatically be added as `akkaSource` When logging via the `ActorContext` the path of the actor will automatically be added as `akkaSource`
Mapped Diagnostic Context (MDC) value. MDC is typically implemented with a `ThreadLocal` by the SLF4J backend. Mapped Diagnostic Context (MDC) value. MDC is typically implemented with a `ThreadLocal` by the SLF4J backend.
To reduce performance impact this MDC value is set when you access the @scala[`log`]@java[`getLog`] method so To reduce performance impact, this MDC value is set when you access the @scala[`log`]@java[`getLog`] method so
you shouldn't cache the returned `Logger` in your own field. That is handled by `ActorContext` and retrieving you shouldn't cache the returned `Logger` in your own field. That is handled by `ActorContext` and retrieving
the `Logger` repeatedly with the @scala[`log`]@java[`getLog`] method has low overhead. the `Logger` repeatedly with the @scala[`log`]@java[`getLog`] method has low overhead.
The MDC is cleared automatically after processing of current message has finished. The MDC is cleared automatically after processing of current message has finished.
@ -127,7 +127,7 @@ Java
## MDC ## MDC
[MDC](http://logback.qos.ch/manual/mdc.html) allows for adding additional context dependent attributes to log entries. [MDC](http://logback.qos.ch/manual/mdc.html) allows for adding additional context dependent attributes to log entries.
Out of the box Akka will place the path of the actor in the the MDC attribute `akkaSource`. Out of the box, Akka will place the path of the actor in the the MDC attribute `akkaSource`.
One or more tags can also be added to the MDC using the `ActorTags` props. The tags will be rendered as a comma separated One or more tags can also be added to the MDC using the `ActorTags` props. The tags will be rendered as a comma separated
list and be put in the MDC attribute `akkaTags`. This can be used to categorize log entries from a set of different actors list and be put in the MDC attribute `akkaTags`. This can be used to categorize log entries from a set of different actors
@ -151,8 +151,8 @@ Scala
Java Java
: @@snip [LoggingDocExamples.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/LoggingDocExamples.java) { #withMdc } : @@snip [LoggingDocExamples.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/LoggingDocExamples.java) { #withMdc }
If you use the MDC API directly, be aware of that MDC is typically implemented with a `ThreadLocal` by the SLF4J backend. If you use the MDC API directly, be aware that MDC is typically implemented with a `ThreadLocal` by the SLF4J backend.
Akka clears the MDC if logging is performed via the @scala[`log`]@java[`getLog`] of the `ActorContext` the MDC is cleared Akka clears the MDC if logging is performed via the @scala[`log`]@java[`getLog`] of the `ActorContext` and it is cleared
automatically after processing of current message has finished, but only if you accessed @scala[`log`]@java[`getLog`]. automatically after processing of current message has finished, but only if you accessed @scala[`log`]@java[`getLog`].
The entire MDC is cleared, including attributes that you add yourself to the MDC. The entire MDC is cleared, including attributes that you add yourself to the MDC.
MDC is not cleared automatically if you use a `Logger` via `LoggerFactory` or not touch @scala[`log`]@java[`getLog`] MDC is not cleared automatically if you use a `Logger` via `LoggerFactory` or not touch @scala[`log`]@java[`getLog`]
@ -220,8 +220,8 @@ logging configuration in `src/test/resources/logback-test.xml`.
#### MDC values #### MDC values
When logging via the @scala[`log`]@java[`getLog`] of the `ActorContext` as described in When logging via the @scala[`log`]@java[`getLog`] of the `ActorContext`, as described in
@ref:[How to log](#how-to-log) Akka includes a few MDC properties: @ref:[How to log](#how-to-log), Akka includes a few MDC properties:
* `akkaSource`: the actor's path * `akkaSource`: the actor's path
* `akkaAddress`: the full address of the ActorSystem, including hostname and port if Cluster is enabled * `akkaAddress`: the full address of the ActorSystem, including hostname and port if Cluster is enabled
@ -397,7 +397,7 @@ akka.remote.artery {
### MDC values from Akka internal logging ### MDC values from Akka internal logging
Since the logging is done asynchronously the thread in which the logging was performed is captured in Since the logging is done asynchronously, the thread in which the logging was performed is captured in
MDC with attribute name `sourceThread`. MDC with attribute name `sourceThread`.
The path of the actor in which the logging was performed is available in the MDC with attribute name `akkaSource`. The path of the actor in which the logging was performed is available in the MDC with attribute name `akkaSource`.
@ -413,23 +413,6 @@ when the underlying logger implementation is called, which can be surprising at
If you want to more accurately output the timestamp for such loggers, use the MDC attribute `akkaTimestamp`. Note that 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. the MDC key will not have any value for a typed actor.
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):
```
<encoder>
<pattern>%date{ISO8601} %-5level %logger{36} %X{akkaSource} - %msg%n</pattern>
</encoder>
```
All MDC properties as key-value entries can be included with `%mdc`:
```
<encoder>
<pattern>%date{ISO8601} %-5level %logger{36} - %msg MDC: {%mdc}%n</pattern>
</encoder>
```
### Markers ### Markers
Akka is logging some events with markers. Some of these events also include structured MDC properties. Akka is logging some events with markers. Some of these events also include structured MDC properties.