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
43 changes: 43 additions & 0 deletions docs/user/tutorial-asgi.rst
Expand Up @@ -967,6 +967,49 @@ 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could add "This section applies also when using WSGI application"


By default, Falcon does not set up logging for you, but Python's built-in `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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC, we have intersphinx connected to the stdlib's docs, so you probably can even link to them:

:mod:`logging`

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah had not seen there was an intersphinx mapping. Doing this change.


.. code:: python

import logging

logging.basicConfig(
format='%(asctime)s [%(levelname)s] %(message)s',
level=logging.INFO
)

logger = logging.getLogger(__name__)

You can now use `logger` to log messages within your application. For example:

.. code:: python

logger.info('Info message')
logger.warning('Warning message')
logger.error('Error message')

It's especially useful to log exceptions and error messages that can help diagnose issues:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good intro on logging, but IMHO the reader of this second tutorial is already expected to be an experienced Python developer, so maybe we could shorten this generic section a bit, and tell more about Falcon's default Exception handler?

In addition to rendering an HTTP 500 response, it does log a message to the falcon logger. Maybe we could even show how this looks like?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah totally makes sense. Is something like this what you have in mind?

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())


.. code:: python

try:
# Some operation...
except Exception as e:
logger.exception('An error occurred: %s', str(e))


For more sophisticated logging setups (e.g., different log levels or formats for development and production), you can configure multiple handlers and formatters, as described in the Python logging `documentation <https://docs.python.org/3/howto/logging.html#logging-basic-tutorial>`__.


.. 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