diff --git a/docs/user/tutorial-asgi.rst b/docs/user/tutorial-asgi.rst index dff2206b2..dd7c63b20 100644 --- a/docs/user/tutorial-asgi.rst +++ b/docs/user/tutorial-asgi.rst @@ -964,6 +964,54 @@ 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 +--------------------------- +(This section also applies to WSGI applications) + +While developing and testing ASGI applications, understanding how to configure +and utilize logging can be helpful, especially when you encounter unexpected +issues or behaviors. + +By default, Falcon does not set up logging for you, +but Python's built-in :mod:`logging` module provides a flexible framework for +emitting and capturing log messages. Here's how you can set up basic logging in +your ASGI Falcon application: + +.. code:: python + + import falcon + import logging + + logging.basicConfig(level=logging.INFO) + + class ErrorResource: + def on_get(self, req, resp): + raise Exception('Something went wrong!') + + 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: + +.. code-block:: none + + ERROR:falcon.asgi.app:Unhandled exception in ASGI application + Traceback (most recent call last): + File "path/to/falcon/app.py", line 123, in __call__ + resp = resource.on_get(req, resp) + File "/path/to/your/app.py", line 7, in on_get + 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 + accessible to unauthorized users. + What Now? ---------