chore: add some docs

untitaker · untitaker · commit f721efbb7d43 · 2018-07-27T12:20:48.000+02:00
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,35 @@
+# Getting started with the Sentry SDK for Python
+
+    import sentry_sdk
+    sentry_sdk.init(dsn="https://foo@sentry.io/123")
+
+After initialization, you can capture exceptions like this:
+
+    sentry_sdk.capture_exception(ValueError())
+
+    try:
+        raise ValueError()
+    except Exception:
+        sentry_sdk.capture_exception()
+
+You can create a scope to prepare data to attach to an event:
+
+    with sentry_sdk.get_current_hub().push_scope():
+        with sentry_sdk.configure_scope() as scope:
+            scope.transaction = "my_view_name"
+            scope.set_tag("key", "value")
+            scope.user = {"id": 123}
+
+        # ValueError event will have all that data attached
+        capture_exception(ValueError())  
+
+    # This one not since it is outside of the context manager
+    capture_exception(ValueError())
+
+
+Scopes can be nested. If you call ``push_scope`` inside of the
+``with``-statement again, that scope will be pushed onto a stack. It will also
+inherit all data from the outer scope.
+
+Head over to the other files to check out integrations, which use these
+low-level APIs so you don't have to.
diff --git a/docs/celery.md b/docs/celery.md
@@ -0,0 +1,9 @@
+# Using Flask with Celery
+
+Just add ``CeleryIntegration()`` to your ``integrations`` array. For example, in Django:
+
+    from sentry_sdk.integrations.celery import CeleryIntegration
+    from sentry_sdk.integrations.django import DjangoIntegration
+    from sentry_sdk import init
+
+    init(dsn="https://foo@sentry.io/123", integrations=[DjangoIntegration(), CeleryIntegration()])
diff --git a/docs/django.md b/docs/django.md
@@ -0,0 +1,18 @@
+# Using Sentry with Django
+
+In your ``settings.py``:
+
+    from sentry_sdk.integrations.django import DjangoIntegration
+    from sentry_sdk import init
+
+    init(dsn="https://foo@sentry.io/123", integrations=[DjangoIntegration()])
+
+* All exceptions are reported.
+
+* Request data is attached to your events.
+
+* The current user ID, email and username from ``django.contrib.auth`` is
+  attached to your events.
+
+* Logging with any logger will create breadcrumbs. See logging docs for more
+  information.
diff --git a/docs/flask.md b/docs/flask.md
@@ -0,0 +1,22 @@
+# Using Sentry with Flask
+
+    from sentry_sdk.integrations.flask import FlaskIntegration
+    from sentry_sdk import init
+
+    init(dsn="https://foo@sentry.io/123", integrations=[FlaskIntegration()])
+
+    app = Flask(__name__)
+
+
+* You can actually run that `init` anywhere. Before or after you define your
+  routes, before or after you register extensions.
+
+* The Flask integration will be installed for all of your apps. It hooks into
+  Flask's signals, not anything on the app object.
+
+* Request data is attached to all events.
+
+* All exceptions leading to a Internal Server Error are reported.
+
+* Logging with `app.logger` or really *any* logger will create breadcrumbs. See
+  logging docs for more information.
diff --git a/docs/logging.md b/docs/logging.md
@@ -0,0 +1,28 @@
+# Using Sentry with stdlib logging
+
+Calling ``sentry_sdk.init()`` already captures any logging message with a level
+higher than or equal to ``INFO``. You can change this behavior by explicitly
+passing the logging integration like any other:
+
+    from sentry_sdk.integrations.logging import LoggingIntegration
+    from sentry_sdk import init
+
+    sentry_logging = LoggingIntegration(
+        level=logging.DEBUG,
+        event_level=logging.ERROR
+    )
+    init(dsn="https://foo@sentry.io/123", integrations=[sentry_logging])
+
+The above configuration captures *all* messages, now including ``DEBUG``, as
+breadcrumbs. Messages with level ``ERROR`` and above will show up as their own
+events as well.
+
+## Config
+
+* ``level`` (default ``INFO``): Log records with a level higher than or equal
+  to ``level`` will be recorded as breadcrumbs. Any log record with a level
+  lower than this one is completely ignored.
+
+* ``event_level`` (default ``None``): Log records with a level higher than or
+  equal to ``event_level`` will additionally be reported as event. A value of
+  ``None`` means that no log records will be sent as events.
