forked from orbit-oss/flask
rewrite debugging docs, move to separate page
This commit is contained in:
David Lord
parent
d25ee22e34
commit
89d1487b2e
5 changed files with 130 additions and 102 deletions
|
|
@ -242,7 +242,6 @@ you can use relative redirects by prefixing the endpoint with a dot only::
|
|||
This will link to ``admin.index`` for instance in case the current request
|
||||
was dispatched to any other admin blueprint endpoint.
|
||||
|
||||
.. _my-blueprint-error-label:
|
||||
|
||||
Blueprint Error Handlers
|
||||
------------------------
|
||||
|
|
|
|||
97
docs/debugging.rst
Normal file
97
docs/debugging.rst
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
Debugging Application Errors
|
||||
============================
|
||||
|
||||
|
||||
In Production
|
||||
-------------
|
||||
|
||||
**Do not run the development server, or enable the built-in debugger, in
|
||||
a production environment.** The debugger allows executing arbitrary
|
||||
Python code from the browser. It's protected by a pin, but that should
|
||||
not be relied on for security.
|
||||
|
||||
Use an error logging tool, such as Sentry, as described in
|
||||
:ref:`error-logging-tools`, or enable logging and notifications as
|
||||
described in :doc:`/logging`.
|
||||
|
||||
If you have access to the server, you could add some code to start an
|
||||
external debugger if ``request.remote_addr`` matches your IP. Some IDE
|
||||
debuggers also have a remote mode so breakpoints on the server can be
|
||||
interacted with locally. Only enable a debugger temporarily.
|
||||
|
||||
|
||||
The Built-In Debugger
|
||||
---------------------
|
||||
|
||||
The built-in Werkzeug development server provides a debugger which shows
|
||||
an interactive traceback in the browser when an unhandled error occurs
|
||||
during a request. This debugger should only be used during development.
|
||||
|
||||
.. image:: _static/debugger.png
|
||||
:align: center
|
||||
:class: screenshot
|
||||
:alt: screenshot of debugger in action
|
||||
|
||||
.. warning::
|
||||
|
||||
The debugger allows executing arbitrary Python code from the
|
||||
browser. It is protected by a pin, but still represents a major
|
||||
security risk. Do not run the development server or debugger in a
|
||||
production environment.
|
||||
|
||||
To enable the debugger, run the development server with the
|
||||
``FLASK_ENV`` environment variable set to ``development``. This puts
|
||||
Flask in debug mode, which changes how it handles some errors, and
|
||||
enables the debugger and reloader.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
$ export FLASK_ENV=development
|
||||
$ flask run
|
||||
|
||||
``FLASK_ENV`` can only be set as an environment variable. When running
|
||||
from Python code, passing ``debug=True`` enables debug mode, which is
|
||||
mostly equivalent. Debug mode can be controled separately from
|
||||
``FLASK_ENV`` with the ``FLASK_DEBUG`` environment variable as well.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.run(debug=True)
|
||||
|
||||
:doc:`/server` and :doc:`/cli` have more information about running the
|
||||
debugger, debug mode, and development mode. More information about the
|
||||
debugger can be found in the `Werkzeug documentation
|
||||
<https://werkzeug.palletsprojects.com/debug/>`__.
|
||||
|
||||
|
||||
External Debuggers
|
||||
------------------
|
||||
|
||||
External debuggers, such as those provided by IDEs, can offer a more
|
||||
powerful debugging experience than the built-in debugger. They can also
|
||||
be used to step through code during a request before an error is raised,
|
||||
or if no error is raised. Some even have a remote mode so you can debug
|
||||
code running on another machine.
|
||||
|
||||
When using an external debugger, the app should still be in debug mode,
|
||||
but it can be useful to disable the built-in debugger and reloader,
|
||||
which can interfere.
|
||||
|
||||
When running from the command line:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
$ export FLASK_ENV=development
|
||||
$ flask run --no-debugger --no-reload
|
||||
|
||||
When running from Python:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.run(debug=True, use_debugger=False, use_reloader=False)
|
||||
|
||||
Disabling these isn't required, an external debugger will continue to
|
||||
work with the following caveats. If the built-in debugger is not
|
||||
disabled, it will catch unhandled exceptions before the external
|
||||
debugger can. If the reloader is not disabled, it could cause an
|
||||
unexpected reload if code changes during debugging.
|
||||
|
|
@ -73,8 +73,6 @@ See also:
|
|||
- `Flask-specific documentation <https://docs.sentry.io/platforms/python/flask/>`__
|
||||
|
||||
|
||||
.. _error-handlers:
|
||||
|
||||
Error Handlers
|
||||
--------------
|
||||
|
||||
|
|
@ -529,63 +527,12 @@ parameter.
|
|||
Logging
|
||||
-------
|
||||
|
||||
See :doc:`/logging` for information on how to log exceptions, such as by
|
||||
emailing them to admins.
|
||||
|
||||
Debugging Application Errors
|
||||
============================
|
||||
|
||||
For production applications, configure your application with logging and
|
||||
notifications as described in :doc:`/logging`. This section provides
|
||||
pointers when debugging deployment configuration and digging deeper with a
|
||||
full-featured Python debugger.
|
||||
|
||||
When in Doubt, Run Manually
|
||||
---------------------------
|
||||
|
||||
Having problems getting your application configured for production? If you
|
||||
have shell access to your host, verify that you can run your application
|
||||
manually from the shell in the deployment environment. Be sure to run under
|
||||
the same user account as the configured deployment to troubleshoot permission
|
||||
issues. You can use Flask's builtin development server with `debug=True` on
|
||||
your production host, which is helpful in catching configuration issues, but
|
||||
**be sure to do this temporarily in a controlled environment.** Do not run in
|
||||
production with `debug=True`.
|
||||
See :doc:`/logging` for information about how to log exceptions, such as
|
||||
by emailing them to admins.
|
||||
|
||||
|
||||
.. _working-with-debuggers:
|
||||
Debugging
|
||||
---------
|
||||
|
||||
Working with Debuggers
|
||||
----------------------
|
||||
|
||||
The built-in development server provides a :ref:`debug-mode` that shows
|
||||
an interactive traceback in the browser when an unhandled error occurs
|
||||
during a request.
|
||||
|
||||
External debuggers, such as those provided by IDEs, can offer a much
|
||||
more powerful and visual debugging experience. They can also be used to
|
||||
step through code during a request before an error is raised, or if no
|
||||
error is raised.
|
||||
|
||||
When using an external debugger, the app should still be in debug mode,
|
||||
but it can be useful to disable the built-in debugger and reloader,
|
||||
which can interfere.
|
||||
|
||||
When running from the command line:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
$ export FLASK_ENV=development
|
||||
$ flask run --no-debugger --no-reload
|
||||
|
||||
When running from Python:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.run(debug=True, use_debugger=False, use_reloader=False)
|
||||
|
||||
Disabling these isn't required, an external debugger will continue to
|
||||
work with the following caveats. If the built-in debugger is not
|
||||
disabled, it will catch unhandled exceptions before the external
|
||||
debugger can. If the reloader is not disabled, it could cause an
|
||||
unexpected reload if code changes during debugging.
|
||||
See :doc:`/debugging` for information about how to debug errors in
|
||||
development and production.
|
||||
|
|
|
|||
|
|
@ -44,6 +44,7 @@ instructions for web development with Flask.
|
|||
templating
|
||||
testing
|
||||
errorhandling
|
||||
debugging
|
||||
logging
|
||||
config
|
||||
signals
|
||||
|
|
|
|||
|
|
@ -111,59 +111,43 @@ application). It will tell you what it tried to import and why it failed.
|
|||
The most common reason is a typo or because you did not actually create an
|
||||
``app`` object.
|
||||
|
||||
.. _debug-mode:
|
||||
|
||||
Debug Mode
|
||||
----------
|
||||
|
||||
(Want to just log errors and stack traces? See :doc:`errorhandling`)
|
||||
The ``flask run`` command can do more than just start the development
|
||||
server. By enabling debug mode, the server will automatically reload if
|
||||
code changes, and will show an interactive debugger in the browser if an
|
||||
error occurs during a request.
|
||||
|
||||
The :command:`flask` script is nice to start a local development server, but
|
||||
you would have to restart it manually after each change to your code.
|
||||
That is not very nice and Flask can do better. If you enable debug
|
||||
support the server will reload itself on code changes, and it will also
|
||||
provide you with a helpful debugger if things go wrong.
|
||||
.. image:: _static/debugger.png
|
||||
:align: center
|
||||
:class: screenshot
|
||||
:alt: The interactive debugger in action.
|
||||
|
||||
To enable all development features (including debug mode) you can export
|
||||
the ``FLASK_ENV`` environment variable and set it to ``development``
|
||||
before running the server::
|
||||
.. warning::
|
||||
|
||||
The debugger allows executing arbitrary Python code from the
|
||||
browser. It is protected by a pin, but still represents a major
|
||||
security risk. Do not run the development server or debugger in a
|
||||
production environment.
|
||||
|
||||
To enable all development features, set the ``FLASK_ENV`` environment
|
||||
variable to ``development`` before calling ``flask run``.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
$ export FLASK_ENV=development
|
||||
$ flask run
|
||||
|
||||
(On Windows you need to use ``set`` instead of ``export``.)
|
||||
See also:
|
||||
|
||||
This does the following things:
|
||||
|
||||
1. it activates the debugger
|
||||
2. it activates the automatic reloader
|
||||
3. it enables the debug mode on the Flask application.
|
||||
|
||||
You can also control debug mode separately from the environment by
|
||||
exporting ``FLASK_DEBUG=1``.
|
||||
|
||||
There are more parameters that are explained in :doc:`/server`.
|
||||
|
||||
.. admonition:: Attention
|
||||
|
||||
Even though the interactive debugger does not work in forking environments
|
||||
(which makes it nearly impossible to use on production servers), it still
|
||||
allows the execution of arbitrary code. This makes it a major security risk
|
||||
and therefore it **must never be used on production machines**.
|
||||
|
||||
Screenshot of the debugger in action:
|
||||
|
||||
.. image:: _static/debugger.png
|
||||
:align: center
|
||||
:class: screenshot
|
||||
:alt: screenshot of debugger in action
|
||||
|
||||
More information on using the debugger can be found in the `Werkzeug
|
||||
documentation`_.
|
||||
|
||||
.. _Werkzeug documentation: https://werkzeug.palletsprojects.com/debug/#using-the-debugger
|
||||
|
||||
Have another debugger in mind? See :ref:`working-with-debuggers`.
|
||||
- :doc:`/server` and :doc:`/cli` for information about running in
|
||||
development mode.
|
||||
- :doc:`/debugging` for information about using the built-in debugger
|
||||
and other debuggers.
|
||||
- :doc:`/logging` and :doc:`/errorhandling` to log errors and display
|
||||
nice error pages.
|
||||
|
||||
|
||||
HTML Escaping
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue