From 0af963114f0870c3f13b23957c9e06be43533b91 Mon Sep 17 00:00:00 2001
From: Anton Pirker <anton.pirker@sentry.io>
Date: Wed, 20 Sep 2023 08:40:42 +0200
Subject: [PATCH] Python: Getting Started logging (#7860)

* Getting Started: logging

* style(lint): Auto commit lint changes

* Apply suggestions from code review

Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>

---------

Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>
---
 src/platforms/python/guides/logging/index.mdx | 91 ++++++++++++-------
 1 file changed, 58 insertions(+), 33 deletions(-)

diff --git a/src/platforms/python/guides/logging/index.mdx b/src/platforms/python/guides/logging/index.mdx
index 8a9f19abbe1c7..85114252ef2b7 100644
--- a/src/platforms/python/guides/logging/index.mdx
+++ b/src/platforms/python/guides/logging/index.mdx
@@ -6,69 +6,78 @@ redirect_from:
 description: "Learn about logging with Python."
 ---
 
-Calling `sentry_sdk.init()` already integrates with the logging module. It is
-equivalent to this explicit configuration:
+Adds support for Python logging.
+
+## Install
+
+Install `sentry-sdk` from PyPI:
+
+```bash
+pip install --upgrade sentry-sdk
+```
+
+## Configure
+
+The logging integrations is a default integration so it will be enabled automatically when you initialize the Sentry SDK.
 
 <SignInNote />
 
 ```python
-import logging
 import sentry_sdk
-from sentry_sdk.integrations.logging import LoggingIntegration
 
-# All of this is already happening by default!
-sentry_logging = LoggingIntegration(
-    level=logging.INFO,        # Capture info and above as breadcrumbs
-    event_level=logging.ERROR  # Send errors as events
-)
 sentry_sdk.init(
     dsn="___PUBLIC_DSN___",
-    integrations=[
-        sentry_logging,
-    ],
-
     # Set traces_sample_rate to 1.0 to capture 100%
     # of transactions for performance monitoring.
-    # We recommend adjusting this value in production,
     traces_sample_rate=1.0,
 )
 ```
 
-## Usage
+## Verify
 
 ```python
 import logging
-logging.debug("I am ignored")
-logging.info("I am a breadcrumb")
-logging.error("I am an event", extra=dict(bar=43))
-logging.exception("An exception happened")
+
+def main():
+    sentry_sdk.init(...)  # same as above
+
+    logging.debug("I am ignored")
+    logging.info("I am a breadcrumb")
+    logging.error("I am an event", extra=dict(bar=43))
+    logging.exception("An exception happened")
+
+main()
 ```
 
 - There will be an error event with the message `"I am an event"`.
 - `"I am a breadcrumb"` will be attached as a breadcrumb to that event.
 - `bar` will end up in the event's `extra` attributes.
 - `"An exception happened"` will send the current exception from `sys.exc_info()` with the stack trace and everything to the Sentry Python SDK. If there's no exception, the current stack will be attached.
-- The debug message `"I am ignored"` will not surface anywhere. To capture it, you need to lower `level` to `DEBUG`.
+- The debug message `"I am ignored"` will not surface anywhere. To capture it, you need to lower `level` to `DEBUG` (See below).
 
-## Ignoring a logger
+## Options
 
-Sometimes a logger is extremely noisy and spams you with pointless errors. You can completely ignore that logger by calling `ignore_logger`:
+To change the default behavior of the logging integration, instantiate the integration manually and pass it to Sentry's `init` function:
 
 ```python
-from sentry_sdk.integrations.logging import ignore_logger
-
-
-ignore_logger("a.spammy.logger")
+import logging
+import sentry_sdk
+from sentry_sdk.integrations.logging import LoggingIntegration
 
-logger = logging.getLogger("a.spammy.logger")
-logger.error("hi")  # no error sent to sentry
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    # Set traces_sample_rate to 1.0 to capture 100%
+    # of transactions for performance monitoring.
+    traces_sample_rate=1.0,
+    integrations=[
+        LoggingIntegration(
+            level=logging.INFO,        # Capture info and above as breadcrumbs
+            event_level=logging.ERROR  # Send errors as events
+        ),
+    ],
+)
 ```
 
-You can also use `before-send` and `before-breadcrumb` to ignore
-only certain messages. See [_Filtering Events_](configuration/filtering/) for more information.
-
-## Options
-
 You can pass the following keyword arguments to `LoggingIntegration()`:
 
 - `level` (default `INFO`): The Sentry Python SDK will record log records with a level higher than or equal to `level` as breadcrumbs. Inversely, the SDK completely ignores any log record with a level lower than this one. If a value of `None` occurs, the SDK won't send log records as breadcrumbs.
@@ -81,6 +90,22 @@ The Sentry Python SDK will honor the configured level of each logger (set with `
 
 </Alert>
 
+## Ignoring a logger
+
+Sometimes a logger is extremely noisy and spams you with pointless errors. You can ignore that logger by calling `ignore_logger`:
+
+```python
+from sentry_sdk.integrations.logging import ignore_logger
+
+ignore_logger("a.spammy.logger")
+
+logger = logging.getLogger("a.spammy.logger")
+logger.error("hi")  # no error sent to sentry
+```
+
+You can also use `before-send` and `before-breadcrumb` to ignore
+only certain messages. See [_Filtering Events_](configuration/filtering/) for more information.
+
 ## Handler classes
 
 Instead of using `LoggingIntegration`, you can use two regular logging `logging.Handler` subclasses that the integration exports.