From 2ef50cb0544a1d47dab9b0907cdbbb963c788b49 Mon Sep 17 00:00:00 2001
From: Patrik Nordwall <patrik.nordwall@gmail.com>
Date: Mon, 25 Nov 2019 17:06:13 +0100
Subject: [PATCH] clarify async appender (#28241)

* increase queue size in prod example
* remove async from dev example
* links to ELK-stack
---
 .../src/test/resources/logback-doc-dev.xml         |  8 +-------
 .../src/test/resources/logback-doc-prod.xml        |  2 +-
 akka-docs/src/main/paradox/typed/logging.md        | 14 ++++++++++++++
 3 files changed, 16 insertions(+), 8 deletions(-)

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 7c415ee4ab..9c00c6edea 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
@@ -17,14 +17,8 @@
         </encoder>
     </appender>
 
-    <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
-        <queueSize>1024</queueSize>
-        <neverBlock>true</neverBlock>
-        <appender-ref ref="FILE" />
-    </appender>
-
     <root level="DEBUG">
         <appender-ref ref="STDOUT"/>
-        <appender-ref ref="ASYNC"/>
+        <appender-ref ref="FILE"/>
     </root>
 </configuration>
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 569eeaea8a..882b724863 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
@@ -13,7 +13,7 @@
     </appender>
 
     <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
-        <queueSize>1024</queueSize>
+        <queueSize>8192</queueSize>
         <neverBlock>true</neverBlock>
         <appender-ref ref="FILE" />
     </appender>
diff --git a/akka-docs/src/main/paradox/typed/logging.md b/akka-docs/src/main/paradox/typed/logging.md
index 8ddcd305c0..3e69bc3443 100644
--- a/akka-docs/src/main/paradox/typed/logging.md
+++ b/akka-docs/src/main/paradox/typed/logging.md
@@ -196,6 +196,20 @@ A starting point for configuration of `logback.xml` for production:
 
 @@snip [logback.xml](/akka-actor-typed-tests/src/test/resources/logback-doc-prod.xml)
 
+Note that the `AsyncAppender` may drop log events if the queue becomes full, which may happen if the
+logging backend can't keep up with the throughput of produced log events. Dropping log events is necessary
+if you want to gracefully degrade your application if only your logging backend or filesystem is experiencing
+issues. 
+
+An alternative of the Logback `AsyncAppender` with better performance is the [Logstash async appender](https://github.com/logstash/logstash-logback-encoder#async-appenders).
+
+The ELK-stack is commonly used as logging infrastructure for production:
+
+* [Logstash Logback encoder](https://github.com/logstash/logstash-logback-encoder)
+* [Logstash](https://www.elastic.co/guide/en/logstash/current/index.html)
+* [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)
+* [Kibana](https://www.elastic.co/guide/en/kibana/current/index.html)
+
 For development you might want to log to standard out, but also have all debug level logging to file, like
 in this example: