-
-
Notifications
You must be signed in to change notification settings - Fork 948
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
Changes from 1 commit
437de29
82d8f52
0a0af19
64f54a6
50b2b98
1c1c950
2521890
83f7b41
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -967,6 +967,47 @@ 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 | ||
--------------------------- | ||
|
||
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 `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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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:
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 In addition to rendering an HTTP 500 response, it does log a message to the There was a problem hiding this comment. Choose a reason for hiding this commentThe 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?
|
||
|
||
.. 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. we may want to link to the external logging docs: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yup, good idea. |
||
|
||
.. 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? | ||
--------- | ||
|
||
|
There was a problem hiding this comment.
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"