From 0284fa6abe4bf572ed81ac1511d3160f3f0ce484 Mon Sep 17 00:00:00 2001 From: Alessandro Chitarrini Date: Wed, 30 Oct 2024 12:32:15 +0100 Subject: [PATCH 1/4] Add FAQ entry for error tracebacks in ASGI applications and update tutorial for logging --- docs/user/faq.rst | 44 +++++++++++++++++++++++++++++++++++++ docs/user/tutorial-asgi.rst | 6 ++--- 2 files changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/user/faq.rst b/docs/user/faq.rst index 789379600..913eb00f0 100644 --- a/docs/user/faq.rst +++ b/docs/user/faq.rst @@ -1347,3 +1347,47 @@ Alternatively, you can set the Cookie header directly as demonstrated in this ve To include multiple values, simply use ``"; "`` to separate each name-value pair. For example, if you were to pass ``{'Cookie': 'xxx=yyy; hello=world'}``, you would get ``{'cookies': {'xxx': 'yyy', 'hello': 'world'}}``. + +.. _why-do-i-not-see-error-tracebacks-in-asgi-applications: + +Why do I not see error tracebacks in ASGI applications? +------------------------------------------------------- + +When using Falcon with ASGI servers like Uvicorn, +you might notice that server errors do not display a traceback by default. +This behavior differs from WSGI applications, where errors are logged to `stderr`, +providing detailed tracebacks. + +The reason for this is that ASGI does not define a standardized way to log errors back to the application server, +unlike WSGI. Therefore, you need to configure logging manually to see these tracebacks. + +Here’s how to set up logging in your ASGI Falcon application to capture error tracebacks: + +.. code:: python + + import logging + import falcon + import falcon.asgi + + logging.basicConfig( + format="%(asctime)s [%(levelname)s] %(message)s", + level=logging.INFO + ) + + class ThingsResource: + async def on_get(self, req, resp): + raise ValueError('foo') + + app = falcon.asgi.App() + things = ThingsResource() + app.add_route('/things', things) + +By adding the above logging configuration, you will see tracebacks like this in your console: + +.. code-block:: none + + [ERROR] [FALCON] Unhandled exception in ASGI app + Traceback (most recent call last): + File "<...>", line 12, in on_get + raise ValueError('foo') + ValueError: foo \ No newline at end of file diff --git a/docs/user/tutorial-asgi.rst b/docs/user/tutorial-asgi.rst index 643d87f27..52683e5db 100644 --- a/docs/user/tutorial-asgi.rst +++ b/docs/user/tutorial-asgi.rst @@ -979,10 +979,8 @@ your ASGI Falcon application: .. code:: python import logging - import falcon - logging.basicConfig(level=logging.INFO) class ErrorResource: @@ -992,7 +990,6 @@ your ASGI Falcon application: 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: @@ -1007,6 +1004,9 @@ might look like: raise Exception("Something went wrong!") Exception: Something went wrong! +For additional details on this topic, +please refer to :ref:`why-do-i-not-see-error-tracebacks-in-asgi-applications`. + .. note:: While logging is helpful for development and debugging, be mindful of logging From 32255624187c09a9194ff2c4bdd96047e0a4f6cc Mon Sep 17 00:00:00 2001 From: Alessandro Chitarrini Date: Wed, 30 Oct 2024 12:44:57 +0100 Subject: [PATCH 2/4] Remove unnecessary news fragments and update changelog for ASGI error logging --- docs/_newsfragments/2387.misc.rst | 7 ------- docs/changes/4.1.0.rst | 21 ++++++++++++++++++++- 2 files changed, 20 insertions(+), 8 deletions(-) delete mode 100644 docs/_newsfragments/2387.misc.rst diff --git a/docs/_newsfragments/2387.misc.rst b/docs/_newsfragments/2387.misc.rst deleted file mode 100644 index 0aa219996..000000000 --- a/docs/_newsfragments/2387.misc.rst +++ /dev/null @@ -1,7 +0,0 @@ -Running mypy on code that uses parts of ``falcon.testing`` naively -would lead to errors like:: - - Name "falcon.testing.TestClient" is not defined - -This has been fixed by explicitly exporting the names that are -imported in the ``falcon.testing`` namespace. diff --git a/docs/changes/4.1.0.rst b/docs/changes/4.1.0.rst index c9a6f005a..b9ca2fbd5 100644 --- a/docs/changes/4.1.0.rst +++ b/docs/changes/4.1.0.rst @@ -14,9 +14,28 @@ Changes to Supported Platforms .. NOTE(vytas): No changes to the supported platforms (yet). - .. towncrier release notes start + +Misc +---- + +- Running mypy on code that uses parts of ``falcon.testing`` naively + would lead to errors like:: + + Name "falcon.testing.TestClient" is not defined + + This has been fixed by explicitly exporting the names that are + imported in the ``falcon.testing`` namespace. (`#2387 `__) +- New FAQ Entry on Error Tracebacks in ASGI Applications + ----------------------------------------------------- + + Added a new FAQ entry explaining why error tracebacks do not appear + in ASGI applications by default when using Falcon. The ASGI tutorial + has been updated to include instructions on configuring logging to + capture error tracebacks. (`#2393 `__) (`#2393 `__) + + Contributors to this Release ---------------------------- From b3466486f093a2af38d2bbd11b806a74ca788bc1 Mon Sep 17 00:00:00 2001 From: Alessandro Chitarrini Date: Thu, 31 Oct 2024 17:16:29 +0100 Subject: [PATCH 3/4] Revert "Remove unnecessary news fragments and update changelog for ASGI error logging" This reverts commit 32255624187c09a9194ff2c4bdd96047e0a4f6cc. --- docs/_newsfragments/2387.misc.rst | 7 +++++++ docs/changes/4.1.0.rst | 21 +-------------------- 2 files changed, 8 insertions(+), 20 deletions(-) create mode 100644 docs/_newsfragments/2387.misc.rst diff --git a/docs/_newsfragments/2387.misc.rst b/docs/_newsfragments/2387.misc.rst new file mode 100644 index 000000000..0aa219996 --- /dev/null +++ b/docs/_newsfragments/2387.misc.rst @@ -0,0 +1,7 @@ +Running mypy on code that uses parts of ``falcon.testing`` naively +would lead to errors like:: + + Name "falcon.testing.TestClient" is not defined + +This has been fixed by explicitly exporting the names that are +imported in the ``falcon.testing`` namespace. diff --git a/docs/changes/4.1.0.rst b/docs/changes/4.1.0.rst index b9ca2fbd5..c9a6f005a 100644 --- a/docs/changes/4.1.0.rst +++ b/docs/changes/4.1.0.rst @@ -14,27 +14,8 @@ Changes to Supported Platforms .. NOTE(vytas): No changes to the supported platforms (yet). -.. towncrier release notes start - - -Misc ----- - -- Running mypy on code that uses parts of ``falcon.testing`` naively - would lead to errors like:: - - Name "falcon.testing.TestClient" is not defined - - This has been fixed by explicitly exporting the names that are - imported in the ``falcon.testing`` namespace. (`#2387 `__) -- New FAQ Entry on Error Tracebacks in ASGI Applications - ----------------------------------------------------- - - Added a new FAQ entry explaining why error tracebacks do not appear - in ASGI applications by default when using Falcon. The ASGI tutorial - has been updated to include instructions on configuring logging to - capture error tracebacks. (`#2393 `__) (`#2393 `__) +.. towncrier release notes start Contributors to this Release ---------------------------- From 346e466eb150f098d230802e8602a392d448f676 Mon Sep 17 00:00:00 2001 From: Alessandro Chitarrini Date: Thu, 31 Oct 2024 17:20:36 +0100 Subject: [PATCH 4/4] moved link to related topic from faq to tutorial-asgi --- docs/user/faq.rst | 7 ++++--- docs/user/tutorial-asgi.rst | 6 ++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/user/faq.rst b/docs/user/faq.rst index 913eb00f0..6790c8773 100644 --- a/docs/user/faq.rst +++ b/docs/user/faq.rst @@ -1348,8 +1348,6 @@ To include multiple values, simply use ``"; "`` to separate each name-value pair. For example, if you were to pass ``{'Cookie': 'xxx=yyy; hello=world'}``, you would get ``{'cookies': {'xxx': 'yyy', 'hello': 'world'}}``. -.. _why-do-i-not-see-error-tracebacks-in-asgi-applications: - Why do I not see error tracebacks in ASGI applications? ------------------------------------------------------- @@ -1390,4 +1388,7 @@ By adding the above logging configuration, you will see tracebacks like this in Traceback (most recent call last): File "<...>", line 12, in on_get raise ValueError('foo') - ValueError: foo \ No newline at end of file + ValueError: foo + +For additional details on this topic, +please refer to :ref:`debugging-asgi-applications`. \ No newline at end of file diff --git a/docs/user/tutorial-asgi.rst b/docs/user/tutorial-asgi.rst index 52683e5db..8450a9efd 100644 --- a/docs/user/tutorial-asgi.rst +++ b/docs/user/tutorial-asgi.rst @@ -963,6 +963,8 @@ 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: + Debugging ASGI Applications --------------------------- (This section also applies to WSGI applications) @@ -1004,10 +1006,6 @@ might look like: raise Exception("Something went wrong!") Exception: Something went wrong! -For additional details on this topic, -please refer to :ref:`why-do-i-not-see-error-tracebacks-in-asgi-applications`. - - .. 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