Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(asgi-tutorial): include info on setting up logging for debugging #2223

Merged
merged 8 commits into from May 7, 2024
48 changes: 48 additions & 0 deletions docs/user/tutorial-asgi.rst
Expand Up @@ -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?
---------

Expand Down