CINXE.COM

<!DOCTYPE html> <html lang="en" data-content_root="../"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Logging — Flask Documentation (3.1.x)</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=4f649999" /> <link rel="stylesheet" type="text/css" href="../_static/flask.css?v=b87c8d14" /> <script src="../_static/documentation_options.js?v=d71c4578"></script> <script src="../_static/doctools.js?v=9bcbadda"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <link rel="canonical" href="https://flask.palletsprojects.com/en/stable/logging/" /> <link rel="icon" href="../_static/shortcut-icon.png"/> <link rel="index" title="Index" href="../genindex/" /> <link rel="search" title="Search" href="../search/" /> <link rel="next" title="Configuration Handling" href="../config/" /> <link rel="prev" title="Debugging Application Errors" href="../debugging/" /> <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="flask" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/logging/" /><meta name="readthedocs-http-status" content="200" /></head><body> <div class="related" role="navigation" aria-label="Related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex/" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex/" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="../config/" title="Configuration Handling" accesskey="N">next</a> |</li> <li class="right" > <a href="../debugging/" title="Debugging Application Errors" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../">Flask Documentation (3.1.x)</a> »</li> <li class="nav-item nav-item-this"><a href="">Logging</a></li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="logging"> <h1>Logging<a class="headerlink" href="#logging" title="Link to this heading">¶</a></h1> Flask uses standard Python <a class="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate">logging</code></a>. Messages about your Flask application are logged with <a class="reference internal" href="../api/#flask.Flask.logger" title="flask.Flask.logger"><code class="xref py py-meth docutils literal notranslate">app.logger</code></a>, which takes the same name as <a class="reference internal" href="../api/#flask.Flask.name" title="flask.Flask.name"><code class="xref py py-attr docutils literal notranslate">app.name</code></a>. This logger can also be used to log your own messages. <div class="highlight-python notranslate"><div class="highlight"><pre>@app.route('/login', methods=['POST']) def login(): user = get_user(request.form['username']) if user.check_password(request.form['password']): login_user(user) app.logger.info('%s logged in successfully', user.username) return redirect(url_for('index')) else: app.logger.info('%s failed to log in', user.username) abort(401) </pre></div> </div> If you don’t configure logging, Python’s default log level is usually ‘warning’. Nothing below the configured level will be visible. <section id="basic-configuration"> <h2>Basic Configuration<a class="headerlink" href="#basic-configuration" title="Link to this heading">¶</a></h2> When you want to configure logging for your project, you should do it as soon as possible when the program starts. If <a class="reference internal" href="../api/#flask.Flask.logger" title="flask.Flask.logger"><code class="xref py py-meth docutils literal notranslate">app.logger</code></a> is accessed before logging is configured, it will add a default handler. If possible, configure logging before creating the application object. This example uses <a class="reference external" href="https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig" title="(in Python v3.13)"><code class="xref py py-func docutils literal notranslate">dictConfig()</code></a> to create a logging configuration similar to Flask’s default, except for all logs: <div class="highlight-default notranslate"><div class="highlight"><pre>from logging.config import dictConfig dictConfig({ 'version': 1, 'formatters': {'default': { 'format': '[%(asctime)s] %(levelname)s in %(module)s: %(message)s', }}, 'handlers': {'wsgi': { 'class': 'logging.StreamHandler', 'stream': 'ext://flask.logging.wsgi_errors_stream', 'formatter': 'default' }}, 'root': { 'level': 'INFO', 'handlers': ['wsgi'] } }) app = Flask(__name__) </pre></div> </div> <section id="default-configuration"> <h3>Default Configuration<a class="headerlink" href="#default-configuration" title="Link to this heading">¶</a></h3> If you do not configure logging yourself, Flask will add a <a class="reference external" href="https://docs.python.org/3/library/logging.handlers.html#logging.StreamHandler" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate">StreamHandler</code></a> to <a class="reference internal" href="../api/#flask.Flask.logger" title="flask.Flask.logger"><code class="xref py py-meth docutils literal notranslate">app.logger</code></a> automatically. During requests, it will write to the stream specified by the WSGI server in <code class="docutils literal notranslate">environ['wsgi.errors']</code> (which is usually <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.stderr" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate">sys.stderr</code></a>). Outside a request, it will log to <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.stderr" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate">sys.stderr</code></a>. </section> <section id="removing-the-default-handler"> <h3>Removing the Default Handler<a class="headerlink" href="#removing-the-default-handler" title="Link to this heading">¶</a></h3> If you configured logging after accessing <a class="reference internal" href="../api/#flask.Flask.logger" title="flask.Flask.logger"><code class="xref py py-meth docutils literal notranslate">app.logger</code></a>, and need to remove the default handler, you can import and remove it: <div class="highlight-default notranslate"><div class="highlight"><pre>from flask.logging import default_handler app.logger.removeHandler(default_handler) </pre></div> </div> </section> </section> <section id="email-errors-to-admins"> <h2>Email Errors to Admins<a class="headerlink" href="#email-errors-to-admins" title="Link to this heading">¶</a></h2> When running the application on a remote server for production, you probably won’t be looking at the log messages very often. The WSGI server will probably send log messages to a file, and you’ll only check that file if a user tells you something went wrong. To be proactive about discovering and fixing bugs, you can configure a <a class="reference external" href="https://docs.python.org/3/library/logging.handlers.html#logging.handlers.SMTPHandler" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate">logging.handlers.SMTPHandler</code></a> to send an email when errors and higher are logged. <div class="highlight-default notranslate"><div class="highlight"><pre>import logging from logging.handlers import SMTPHandler mail_handler = SMTPHandler( mailhost='127.0.0.1', fromaddr='server-error@example.com', toaddrs=['admin@example.com'], subject='Application Error' ) mail_handler.setLevel(logging.ERROR) mail_handler.setFormatter(logging.Formatter( '[%(asctime)s] %(levelname)s in %(module)s: %(message)s' )) if not app.debug: app.logger.addHandler(mail_handler) </pre></div> </div> This requires that you have an SMTP server set up on the same server. See the Python docs for more information about configuring the handler. </section> <section id="injecting-request-information"> <h2>Injecting Request Information<a class="headerlink" href="#injecting-request-information" title="Link to this heading">¶</a></h2> Seeing more information about the request, such as the IP address, may help debugging some errors. You can subclass <a class="reference external" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate">logging.Formatter</code></a> to inject your own fields that can be used in messages. You can change the formatter for Flask’s default handler, the mail handler defined above, or any other handler. <div class="highlight-default notranslate"><div class="highlight"><pre>from flask import has_request_context, request from flask.logging import default_handler class RequestFormatter(logging.Formatter): def format(self, record): if has_request_context(): record.url = request.url record.remote_addr = request.remote_addr else: record.url = None record.remote_addr = None return super().format(record) formatter = RequestFormatter( '[%(asctime)s] %(remote_addr)s requested %(url)s\n' '%(levelname)s in %(module)s: %(message)s' ) default_handler.setFormatter(formatter) mail_handler.setFormatter(formatter) </pre></div> </div> </section> <section id="other-libraries"> <h2>Other Libraries<a class="headerlink" href="#other-libraries" title="Link to this heading">¶</a></h2> Other libraries may use logging extensively, and you want to see relevant messages from those logs too. The simplest way to do this is to add handlers to the root logger instead of only the app logger. <div class="highlight-default notranslate"><div class="highlight"><pre>from flask.logging import default_handler root = logging.getLogger() root.addHandler(default_handler) root.addHandler(mail_handler) </pre></div> </div> Depending on your project, it may be more useful to configure each logger you care about separately, instead of configuring only the root logger. <div class="highlight-default notranslate"><div class="highlight"><pre>for logger in ( logging.getLogger(app.name), logging.getLogger('sqlalchemy'), logging.getLogger('other_package'), ): logger.addHandler(default_handler) logger.addHandler(mail_handler) </pre></div> </div> <section id="werkzeug"> <h3>Werkzeug<a class="headerlink" href="#werkzeug" title="Link to this heading">¶</a></h3> Werkzeug logs basic request/response information to the <code class="docutils literal notranslate">'werkzeug'</code> logger. If the root logger has no handlers configured, Werkzeug adds a <a class="reference external" href="https://docs.python.org/3/library/logging.handlers.html#logging.StreamHandler" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate">StreamHandler</code></a> to its logger. </section> <section id="flask-extensions"> <h3>Flask Extensions<a class="headerlink" href="#flask-extensions" title="Link to this heading">¶</a></h3> Depending on the situation, an extension may choose to log to <a class="reference internal" href="../api/#flask.Flask.logger" title="flask.Flask.logger"><code class="xref py py-meth docutils literal notranslate">app.logger</code></a> or its own named logger. Consult each extension’s documentation for details. </section> </section> </section> <div class="clearer"></div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="Main"> <div class="sphinxsidebarwrapper"> <a href="../"> <img class="logo" src="../_static/flask-vertical.png" alt="Logo of Flask"/> </a> <h3>Contents</h3> <ul> <li><a class="reference internal" href="#">Logging</a><ul> <li><a class="reference internal" href="#basic-configuration">Basic Configuration</a><ul> <li><a class="reference internal" href="#default-configuration">Default Configuration</a></li> <li><a class="reference internal" href="#removing-the-default-handler">Removing the Default Handler</a></li> </ul> </li> <li><a class="reference internal" href="#email-errors-to-admins">Email Errors to Admins</a></li> <li><a class="reference internal" href="#injecting-request-information">Injecting Request Information</a></li> <li><a class="reference internal" href="#other-libraries">Other Libraries</a><ul> <li><a class="reference internal" href="#werkzeug">Werkzeug</a></li> <li><a class="reference internal" href="#flask-extensions">Flask Extensions</a></li> </ul> </li> </ul> </li> </ul> <h3>Navigation</h3> <ul> <li><a href="../">Overview</a> <ul> <li>Previous: <a href="../debugging/" title="previous chapter">Debugging Application Errors</a> <li>Next: <a href="../config/" title="next chapter">Configuration Handling</a> </ul> </li> </ul> <search id="searchbox" style="display: none" role="search"> <h3 id="searchlabel">Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search/" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </search> <script>document.getElementById('searchbox').style.display = "block"</script><div id="ethical-ad-placement"></div> </div> </div> <div class="clearer"></div> </div> <div class="footer" role="contentinfo"> © Copyright 2010 Pallets. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3. </div> </body> </html>