docs(asgi-tutorial): include info on setting up logging for debugging #2223
Conversation
…ing an application
vytas7
changed the title
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #2223 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 63 63
Lines 6931 6931
Branches 1258 1258
=========================================
Hits 6931 6931 ☔ View full report in Codecov by Sentry. |
docs/user/tutorial-asgi.rst
Outdated
| 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.
we may want to link to the external logging docs: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial
docs/user/tutorial-asgi.rst
Outdated
| 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. |
There was a problem hiding this comment.
We could add "This section applies also when using WSGI application"
docs/user/tutorial-asgi.rst
Outdated
|
|
||
| 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.
IIRC, we have intersphinx connected to the stdlib's docs, so you probably can even link to them:
:mod:`logging`
There was a problem hiding this comment.
Ah had not seen there was an intersphinx mapping. Doing this change.
docs/user/tutorial-asgi.rst
Outdated
| 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.
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?
There was a problem hiding this comment.
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())
docs/user/tutorial-asgi.rst
Outdated
|
|
||
| class ErrorResource: | ||
| def on_get(self, req, resp): | ||
| raise Exception("Something went wrong!") |
There was a problem hiding this comment.
I think we are using single quotes throughout the codebase
There was a problem hiding this comment.
I took the liberty of changing your Exception line to use single quotes, looks good otherwise now, thanks for this improvement!
Another thought is that we probably want to move this section somewhere closer to the start, because it is likely that the reader might encounter errors earlier 🙂 But we can follow up on this later. LGTM as is for now.
|
Oh, it seems that we have some CI fighting to do that is unrelated to the proposed changes 😬 I'll take a look at these tomorrow. Edit: hopefully done with these. |
Summary of Changes
This PR introduces a new section to the ASGI tutorial in the Falcon documentation, aimed at providing developers with clear instructions on setting up and utilizing logging for debugging ASGI applications. The added content outlines the steps to configure basic logging using Python's built-in logging module, offering examples of how to log informational, warning, and error messages effectively.
Related Issues
#2098
Pull Request Checklist
This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once; it will save you a few review cycles!
If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.
docs/.docs/.versionadded,versionchanged, ordeprecateddirectives.docs/_newsfragments/, with the file name format{issue_number}.{fragment_type}.rst. (Runtowncrier --draftto ensure it renders correctly.)If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!
PR template inspired by the attrs project.