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