docs(FAQ): add entry for error tracebacks in ASGI apps

docs/changes/4.1.0.rst

@@ -14,9 +14,28 @@ Changes to Supported Platforms
 
 .. NOTE(vytas): No changes to the supported platforms (yet).
 
-
 .. towncrier release notes start
 
+
+Misc
+----
+
+- Running mypy on code that uses parts of ``falcon.testing`` naively
+  would lead to errors like::
+
+    Name "falcon.testing.TestClient" is not defined
+
+  This has been fixed by explicitly exporting the names that are
+  imported in the ``falcon.testing`` namespace. (`#2387 <https://github.com/falconry/falcon/issues/2387>`__)
+- New FAQ Entry on Error Tracebacks in ASGI Applications
+  -----------------------------------------------------
+
+  Added a new FAQ entry explaining why error tracebacks do not appear 
+  in ASGI applications by default when using Falcon. The ASGI tutorial 
+  has been updated to include instructions on configuring logging to 
+  capture error tracebacks. (`#2393 <https://github.com/falconry/falcon/issues/2393>`__) (`#2393 <https://github.com/falconry/falcon/issues/2393>`__)
+
+
 Contributors to this Release
 ----------------------------
 

docs/user/faq.rst

@@ -1347,3 +1347,47 @@ 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:
+
+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

docs/user/tutorial-asgi.rst

@@ -979,10 +979,8 @@ your ASGI Falcon application:
 .. code:: python
 
     import logging
-
     import falcon
 
-
     logging.basicConfig(level=logging.INFO)
 
     class ErrorResource:
@@ -992,7 +990,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,6 +1004,9 @@ might look like:
         raise Exception("Something went wrong!")
     Exception: Something went wrong!
 
+For additional details on this topic, 
+please refer to :ref:`why-do-i-not-see-error-tracebacks-in-asgi-applications`.
+
 
 .. note::
    While logging is helpful for development and debugging, be mindful of logging