chore: documentation for flask

Author: untitaker

docs/flask.md

@@ -0,0 +1,62 @@
+# Integration with Flask
+
+Easiest way to get started:
+
+    from flask import Flask
+    from sentry_sdk import capture_exception
+    from sentry_sdk.integrations.flask import FlaskSentry
+
+    app = Flask(__name__)
+
+    app.config["SENTRY_DSN"] = "https://[email protected]/123"
+    flask_sentry = FlaskSentry(app)  # A normal flask extension
+
+    # The sentry client is set up, capture_* methods are usable anywhere
+    capture_exception(ValueError())
+
+    @app.route("/")
+    def index():
+        capture_exception(ValueError())
+
+        # logging
+        app.logger.debug("hi")  # this will be a breadcrumb
+        app.logger.debug("oh no")  # this will be an event
+
+        # thrown errors are captured
+        1 / 0  
+
+## Configuration
+
+The Flask extension can be configured through ``app.config``. The valid keys
+are:
+
+* ``SENTRY_FLASK_SETUP_LOGGER``: Whether the sentry logging integration should
+  be set up for ``app.logger``.
+
+Other options starting with ``SENTRY_`` are passed on to ``init`` (such as
+``dsn``)
+
+## Manual configuration
+
+If reading the configuration from ``app.config`` is too much magic for you, you
+can also use the lower-level API like this:
+
+    from flask import Flask
+    from sentry_sdk import init, capture_exception
+    from sentry_sdk.integrations.flask import FlaskIntegration
+
+
+    app = Flask(__name__)
+    # app.config["SENTRY_DSN"] = "garbage"  # would be ignored
+
+    sentry_integration = FlaskIntegration(app, setup_logger=True)
+
+    # client config is passed normally through init
+    init(dsn="https://[email protected]/123", integrations=[sentry_integration])
+
+    # the routes look the same
+
+
+In this example, your configuration for Sentry is separate from your app
+config, and also the config for the Flask integration is separate from your
+general Sentry config.

tests/integrations/flask/test_flask.py

@@ -267,3 +267,16 @@ def index():
         client.get("/")
 
     assert len(capture_events) == 1
+
+
+def test_logging(capture_events, app):
+    @app.route("/")
+    def index():
+        app.logger.error("hi")
+        return "ok"
+
+    client = app.test_client()
+    client.get("/")
+
+    event, = capture_events
+    assert event["level"] == "error"