From ab2ce4c5b41b77baee4d99f9edb01eeefe993b1b Mon Sep 17 00:00:00 2001
From: Alessandro Chitarrini <140112899+chitvs@users.noreply.github.com>
Date: Tue, 5 Nov 2024 16:43:58 +0100
Subject: [PATCH] docs(FAQ): add entry for error tracebacks in ASGI apps
 (#2395)

* Add FAQ entry for error tracebacks in ASGI applications and update tutorial for logging

* Remove unnecessary news fragments and update changelog for ASGI error logging

* Revert "Remove unnecessary news fragments and update changelog for ASGI error logging"

This reverts commit 32255624187c09a9194ff2c4bdd96047e0a4f6cc.

* moved link to related topic from faq to tutorial-asgi

---------

Co-authored-by: Vytautas Liuolia <vytautas.liuolia@gmail.com>
---
 docs/user/faq.rst           | 45 +++++++++++++++++++++++++++++++++++++
 docs/user/tutorial-asgi.rst |  6 ++---
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/docs/user/faq.rst b/docs/user/faq.rst
index 789379600..6790c8773 100644
--- a/docs/user/faq.rst
+++ b/docs/user/faq.rst
@@ -1347,3 +1347,48 @@ Alternatively, you can set the Cookie header directly as demonstrated in this ve
 To include multiple values, simply use ``"; "`` to separate each name-value
 pair. For example, if you were to pass ``{'Cookie': 'xxx=yyy; hello=world'}``,
 you would get ``{'cookies': {'xxx': 'yyy', 'hello': 'world'}}``.
+
+Why do I not see error tracebacks in ASGI applications?
+-------------------------------------------------------
+
+When using Falcon with ASGI servers like Uvicorn,
+you might notice that server errors do not display a traceback by default.
+This behavior differs from WSGI applications, where errors are logged to `stderr`,
+providing detailed tracebacks.
+
+The reason for this is that ASGI does not define a standardized way to log errors back to the application server,
+unlike WSGI. Therefore, you need to configure logging manually to see these tracebacks.
+
+Here’s how to set up logging in your ASGI Falcon application to capture error tracebacks:
+
+.. code:: python
+
+    import logging
+    import falcon
+    import falcon.asgi
+
+    logging.basicConfig(
+        format="%(asctime)s [%(levelname)s] %(message)s", 
+        level=logging.INFO
+    )
+
+    class ThingsResource:
+        async def on_get(self, req, resp):
+            raise ValueError('foo')
+
+    app = falcon.asgi.App()
+    things = ThingsResource()
+    app.add_route('/things', things)
+
+By adding the above logging configuration, you will see tracebacks like this in your console:
+
+.. code-block:: none
+
+    [ERROR] [FALCON] Unhandled exception in ASGI app
+    Traceback (most recent call last):
+    File "<...>", line 12, in on_get
+        raise ValueError('foo')
+    ValueError: foo
+
+For additional details on this topic, 
+please refer to :ref:`debugging-asgi-applications`.
\ No newline at end of file
diff --git a/docs/user/tutorial-asgi.rst b/docs/user/tutorial-asgi.rst
index 643d87f27..8450a9efd 100644
--- a/docs/user/tutorial-asgi.rst
+++ b/docs/user/tutorial-asgi.rst
@@ -963,6 +963,8 @@ adding ``--cov-fail-under=100`` (or any other percent threshold) to our
     tests in multiple environments would most probably involve running
     ``coverage`` directly, and combining results.
 
+.. _debugging-asgi-applications:
+
 Debugging ASGI Applications
 ---------------------------
 (This section also applies to WSGI applications)
@@ -979,10 +981,8 @@ your ASGI Falcon application:
 .. code:: python
 
     import logging
-
     import falcon
 
-
     logging.basicConfig(level=logging.INFO)
 
     class ErrorResource:
@@ -992,7 +992,6 @@ your ASGI Falcon application:
     app = falcon.App()
     app.add_route('/error', ErrorResource())
 
-
 When the above route is accessed, Falcon will catch the unhandled exception and
 automatically log an error message. Below is an example of what the log output
 might look like:
@@ -1007,7 +1006,6 @@ might look like:
         raise Exception("Something went wrong!")
     Exception: Something went wrong!
 
-
 .. note::
    While logging is helpful for development and debugging, be mindful of logging
    sensitive information. Ensure that log files are stored securely and are not