From 2dc0f4ec0032f0ab6dd8a2298aa25409d0645906 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 17 Nov 2025 16:59:30 +0100 Subject: [PATCH 1/4] ref(logging): Update logging integration docs to better integrate Sentry logs --- .../python/integrations/logging/index.mdx | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/platforms/python/integrations/logging/index.mdx b/docs/platforms/python/integrations/logging/index.mdx index 87e03ad88fee6..4306c630847c1 100644 --- a/docs/platforms/python/integrations/logging/index.mdx +++ b/docs/platforms/python/integrations/logging/index.mdx @@ -3,7 +3,7 @@ title: Logging description: "Learn about logging with Python." --- -Adds support for Python logging. +The logging integration adds support for the `logging` framework from Python's standard library. ## Install @@ -19,7 +19,7 @@ uv add "sentry-sdk" ## Configure -The logging integrations is a default integration so it will be enabled automatically when you initialize the Sentry SDK. +To capture log records as [Sentry logs](/platforms/python/logs/), set `enable_logs` to `True`. The logging integration is a default integration, so it will be enabled automatically when you initialize the Sentry SDK. ```python import sentry_sdk @@ -29,45 +29,44 @@ sentry_sdk.init( # Add data like request headers and IP for users, if applicable; # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info send_default_pii=True, + enable_logs=True, ) ``` ## Verify -```python -import logging - -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() -``` +As long as `enable_logs` is `True`, logs with a level of `INFO` and higher will be captured as Sentry logs. The threshold can be configured via the [`sentry_logs_level` option](#options). -- 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` (See below). +Additionally, the logging integration will create an error event from all `ERROR`-level logs. This feature is configurable via the [`event_level` integration option](#options). -Log records can additionally also be captured as [Sentry logs](/platforms/python/logs/) as long as the `enable_logs` option is `True`. +`INFO` and above logs will also be captured as breadcrumbs. Use the [`level` integration option](#options) to adjust the threshold. ```python -import logging import sentry_sdk +from logging import logger sentry_sdk.init( - # ... + ..., enable_logs=True, ) -logging.info("I will be sent to Sentry logs") +# The following will be captured as Sentry logs: +logger.info("I'm an INFO log") +logger.error("I'm an ERROR log", extra={"bar": 43}) +logger.exception("I'm an exception log") + +# DEBUG-level logs won't be captured by default +logger.debug("I'm a DEBUG log") ``` +- All of the above logs except for the `DEBUG` level message will be sent to Sentry as logs. +- An error event with the message `"I'm an exception log"` will be created. +- `"I'm an INFO log"` will be attached as a breadcrumb to that event. +- `bar` will end up in the `extra` attributes of that event. +- `"I'm an exception log"` will send the current exception from `sys.exc_info()` with the stack trace to Sentry. If there's no exception, the current stack will be attached. +- The debug message `"I'm a DEBUG log"` will not be captured by Sentry. See the [`sentry_logs_level` option](#option) to adjust which levels should be sent to Sentry as logs, and the [`level` option](#option) to do adjust the level for capturing breadcrumbs. + + ### Working with Extra Fields When sending log records as Sentry logs, any fields provided in the `extra` dictionary are automatically promoted to top-level attributes on the log entry. This makes them searchable and filterable in the Sentry UI. @@ -115,9 +114,9 @@ sentry_sdk.init( # ... integrations=[ LoggingIntegration( + sentry_logs_level=logging.INFO, # Capture INFO and above as logs level=logging.INFO, # Capture INFO and above as breadcrumbs event_level=logging.ERROR, # Send ERROR records as events - sentry_logs_level=logging.INFO, # Capture INFO and above as logs ), ], ) @@ -125,10 +124,6 @@ sentry_sdk.init( 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. - -- `event_level` (default `ERROR`): The Sentry Python SDK will report log records with a level higher than or equal to `event_level` as events as long as the logger itself is set to output records of those log levels (see note below). If a value of `None` occurs, the SDK won't send log records as events. - - `sentry_logs_level` (default `INFO`): The Sentry Python SDK will capture records with a level higher than or equal to `sentry_logs_level` as [Sentry structured logs](/platforms/python/logs/) as long as the `enable_logs` option is `True`. ```python @@ -138,6 +133,11 @@ 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. + +- `event_level` (default `ERROR`): The Sentry Python SDK will report log records with a level higher than or equal to `event_level` as events as long as the logger itself is set to output records of those log levels (see note below). If a value of `None` occurs, the SDK won't send log records as events. + + The Sentry Python SDK will honor the configured level of each logger (set with `logger.setLevel(level)` or `logging.basicConfig(level=level)`). That means that you will not see any `INFO` or `DEBUG` events from a logger with the level set to `WARNING`, regardless of how you configure the integration. If not set explicitly, the logging level defaults to `WARNING`. From 508d1f4cf24b8b0bbc744c569552beb86362dcfc Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Tue, 18 Nov 2025 07:55:58 +0100 Subject: [PATCH 2/4] tweaks --- .../python/integrations/logging/index.mdx | 30 ++++++++++++++----- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/platforms/python/integrations/logging/index.mdx b/docs/platforms/python/integrations/logging/index.mdx index 4306c630847c1..33a4fdcee81cd 100644 --- a/docs/platforms/python/integrations/logging/index.mdx +++ b/docs/platforms/python/integrations/logging/index.mdx @@ -3,7 +3,7 @@ title: Logging description: "Learn about logging with Python." --- -The logging integration adds support for the `logging` framework from Python's standard library. +The logging integration adds support for the `logging` framework from Python's standard library. Depending on your settings, logs can be captured as Sentry logs, as error events, or as breadcrumbs, or a combination of those. ## Install @@ -35,6 +35,21 @@ sentry_sdk.init( ## Verify +```python +import logging + +def main(): + sentry_sdk.init(...) # same as above + logging.info("Logging some info") + logging.error("Logging an error") + +main() +``` + +This will capture both logs and send them to Sentry Logs. Additionally, an error event will be created from the `ERROR`-level log. In addition to that, a breadcrumb will be created from the `INFO`-level log. + +## Behavior + As long as `enable_logs` is `True`, logs with a level of `INFO` and higher will be captured as Sentry logs. The threshold can be configured via the [`sentry_logs_level` option](#options). Additionally, the logging integration will create an error event from all `ERROR`-level logs. This feature is configurable via the [`event_level` integration option](#options). @@ -42,8 +57,9 @@ Additionally, the logging integration will create an error event from all `ERROR `INFO` and above logs will also be captured as breadcrumbs. Use the [`level` integration option](#options) to adjust the threshold. ```python +import logging + import sentry_sdk -from logging import logger sentry_sdk.init( ..., @@ -51,16 +67,16 @@ sentry_sdk.init( ) # The following will be captured as Sentry logs: -logger.info("I'm an INFO log") -logger.error("I'm an ERROR log", extra={"bar": 43}) -logger.exception("I'm an exception log") +logging.info("I'm an INFO log") +logging.error("I'm an ERROR log", extra={"bar": 43}) +logging.exception("I'm an exception log") # DEBUG-level logs won't be captured by default -logger.debug("I'm a DEBUG log") +logging.debug("I'm a DEBUG log") ``` - All of the above logs except for the `DEBUG` level message will be sent to Sentry as logs. -- An error event with the message `"I'm an exception log"` will be created. +- An error event with the message `"I'm an ERROR log"` will be created. - `"I'm an INFO log"` will be attached as a breadcrumb to that event. - `bar` will end up in the `extra` attributes of that event. - `"I'm an exception log"` will send the current exception from `sys.exc_info()` with the stack trace to Sentry. If there's no exception, the current stack will be attached. From 6d0119e89e317f0991a9baeccc09d489877ff326 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Tue, 18 Nov 2025 11:54:07 +0100 Subject: [PATCH 3/4] alert --- docs/platforms/python/integrations/logging/index.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/platforms/python/integrations/logging/index.mdx b/docs/platforms/python/integrations/logging/index.mdx index 33a4fdcee81cd..131650fcaca3b 100644 --- a/docs/platforms/python/integrations/logging/index.mdx +++ b/docs/platforms/python/integrations/logging/index.mdx @@ -5,6 +5,12 @@ description: "Learn about logging with Python." The logging integration adds support for the `logging` framework from Python's standard library. Depending on your settings, logs can be captured as Sentry logs, as error events, or as breadcrumbs, or a combination of those. + + +Enable the Sentry Logs feature with `sentry_sdk.init(enable_logs=True)` to unlock Sentry's full logging power. With Sentry Logs, you can search, filter, and analyze logs from across your entire application in one place. + + + ## Install Install `sentry-sdk` from PyPI: From 4f6093965c3ca7d07b89b777f2cdd4172d7c4509 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Tue, 18 Nov 2025 12:44:12 +0100 Subject: [PATCH 4/4] clarification --- docs/platforms/python/integrations/logging/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/python/integrations/logging/index.mdx b/docs/platforms/python/integrations/logging/index.mdx index 131650fcaca3b..f70b2963ea502 100644 --- a/docs/platforms/python/integrations/logging/index.mdx +++ b/docs/platforms/python/integrations/logging/index.mdx @@ -56,7 +56,7 @@ This will capture both logs and send them to Sentry Logs. Additionally, an error ## Behavior -As long as `enable_logs` is `True`, logs with a level of `INFO` and higher will be captured as Sentry logs. The threshold can be configured via the [`sentry_logs_level` option](#options). +As long as `enable_logs` is `True`, logs with a level of `INFO` and higher will be captured as Sentry logs if the log level set in the `logging` module is `INFO` or below. The threshold can be configured via the [`sentry_logs_level` option](#options). Additionally, the logging integration will create an error event from all `ERROR`-level logs. This feature is configurable via the [`event_level` integration option](#options).