From bec85d7470bb9ee2038c36cd6a91694be793b570 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Tue, 25 Aug 2026 15:29:37 +0200 Subject: [PATCH] docs(python): Document enable_logs as deprecated, not a no-op Python SDK 2.68.1 restored enable_logs as a compatibility layer. When an integration leaves capture_sentry_logs unset, enable_logs=True turns automatic log capture back on for the logging and Loguru integrations, and an explicit capture_sentry_logs always wins. The docs still described the option as a no-op as of 2.68.0, and listed the capture_sentry_logs default as False rather than unset. Users on enable_logs were told their config had no effect when it does, and users debugging missing logs were pointed only at the new option. Add a precedence table for the two options, correct the integration option defaults to unset, and note that 2.68.0 alone had no effect. Refs https://github.com/getsentry/sentry-python/pull/7237 Co-Authored-By: Claude Opus 5 (1M context) --- docs/platforms/python/configuration/options.mdx | 17 ++++++++++++++--- .../python/integrations/logging/index.mdx | 8 ++++---- .../python/integrations/loguru/index.mdx | 10 +++++----- 3 files changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/platforms/python/configuration/options.mdx b/docs/platforms/python/configuration/options.mdx index 013d2b8ce7829..b0c5e8569ca2c 100644 --- a/docs/platforms/python/configuration/options.mdx +++ b/docs/platforms/python/configuration/options.mdx @@ -626,10 +626,21 @@ Self-hosted Sentry users should set this option to `False`, as standalone `gen_a -Starting from `2.68.0`, this option has no effect. The `sentry_sdk.logger` API works standalone. Automatic capture of logs by integrations is off by default and can be toggled on the integration level with the `capture_sentry_logs` integration option. See the [Logs documentation](/platforms/python/logs#other-logging-integrations) for more details. +**Deprecated:** This option will be removed in the next major version. Use the `capture_sentry_logs` option on the [`logging`](/platforms/python/integrations/logging/#options) and [Loguru](/platforms/python/integrations/loguru/#options) integrations instead. -In older SDK versions (prior to `2.68`), this option had to be set to `True` to be able to use the `sentry_sdk.logger` API. It also enabled automatic capture of logs from the standard library `logging` module as well as from Loguru. +The `sentry_sdk.logger` API works standalone and is not affected by this option. -Made no-op in version `2.68.0`. New in SDK version `2.35.0`. Prior to `2.35.0`, this option was experimental. +For automatic capture of logs from the standard library `logging` module and from Loguru, this option acts as a fallback. If an integration leaves `capture_sentry_logs` unset, `enable_logs=True` turns automatic capture on for that integration. Setting `capture_sentry_logs` on the integration always wins. + +| `enable_logs` | `capture_sentry_logs` | Automatic capture | +| ----------------- | --------------------- | ----------------- | +| not set / `False` | not set | off | +| `True` | not set | on | +| any | `True` | on | +| any | `False` | off | + +In SDK versions prior to `2.68.0`, this option had to be set to `True` to use the `sentry_sdk.logger` API, and it also enabled automatic capture of logs from the standard library `logging` module and from Loguru. In version `2.68.0` only, the option had no effect at all. Upgrade to `2.68.1` or later if you rely on it. + +Deprecated in version `2.68.1`. New in SDK version `2.35.0`. Prior to `2.35.0`, this option was experimental. diff --git a/docs/platforms/python/integrations/logging/index.mdx b/docs/platforms/python/integrations/logging/index.mdx index b22209d7e850b..5cc0d10f6754c 100644 --- a/docs/platforms/python/integrations/logging/index.mdx +++ b/docs/platforms/python/integrations/logging/index.mdx @@ -59,7 +59,7 @@ This will capture both logs and send them to Sentry Logs. Additionally, an error ## Behavior -When `capture_sentry_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). +When the integration is capturing Sentry logs, 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). @@ -156,9 +156,9 @@ sentry_sdk.init( You can pass the following keyword arguments to `LoggingIntegration()`: -- `capture_sentry_logs` (default `False`): Set to `True` to capture log records as [Sentry structured logs](/platforms/python/logs/). +- `capture_sentry_logs` (default: unset, which behaves as `False`): Set to `True` to capture log records as [Sentry structured logs](/platforms/python/logs/). If you leave this unset and have the deprecated [`enable_logs`](/platforms/python/configuration/options/#enable_logs) set to `True`, the SDK captures records as Sentry logs. Setting this option explicitly always wins over `enable_logs`. -- `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 `capture_sentry_logs` is `True`. +- `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 integration is capturing Sentry logs. - `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. @@ -202,7 +202,7 @@ See the [API documentation](https://getsentry.github.io/sentry-python/integratio - First, make sure you're on the latest version of the SDK. If you're using the `sentry_sdk.logger` API directly (e.g., `sentry_sdk.logger.info(...)`), logs are sent automatically. If you're using Python's `logging` module and want those log records captured as Sentry logs, make sure you have `capture_sentry_logs=True` set on your `LoggingIntegration`. + First, make sure you're on the latest version of the SDK. If you're using the `sentry_sdk.logger` API directly (e.g., `sentry_sdk.logger.info(...)`), logs are sent automatically. If you're using Python's `logging` module and want those log records captured as Sentry logs, make sure you have `capture_sentry_logs=True` set on your `LoggingIntegration`. Setting the deprecated `enable_logs=True` also works, but only if `capture_sentry_logs` is left unset on the integration. The 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`. diff --git a/docs/platforms/python/integrations/loguru/index.mdx b/docs/platforms/python/integrations/loguru/index.mdx index 0012586ece176..f297e27eb8f00 100644 --- a/docs/platforms/python/integrations/loguru/index.mdx +++ b/docs/platforms/python/integrations/loguru/index.mdx @@ -63,7 +63,7 @@ This will capture both logs and send them to Sentry Logs. Additionally, an error ## Behavior -Logs with a level of `INFO` and higher will be captured as Sentry logs as long as `capture_sentry_logs` is `True` and the log level set in the `logging` module is `INFO` or below. The threshold can be configured via the [`sentry_logs_level` option](#options). +Logs with a level of `INFO` and higher will be captured as Sentry logs as long as the integration is capturing Sentry logs and 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 Loguru integration will create an error event from all `ERROR`-level logs. This feature is configurable via the [`event_level` integration option](#options). @@ -156,13 +156,13 @@ sentry_sdk.init( - `capture_sentry_logs` - Set to `True` to capture Loguru log records as [Sentry structured logs](/platforms/python/logs/). + Set to `True` to capture Loguru log records as [Sentry structured logs](/platforms/python/logs/). If you leave this unset and have the deprecated [`enable_logs`](/platforms/python/configuration/options/#enable_logs) set to `True`, the SDK captures records as Sentry logs. Setting this option explicitly always wins over `enable_logs`. - Default: `False` + Default: unset, which behaves as `False` - `sentry_logs_level` - The Sentry Python SDK will capture log records with a level higher than or equal to `sentry_logs_level` as [Sentry structured logs](/platforms/python/logs/). If set to `None`, the SDK won't send records as logs. Only applies when `capture_sentry_logs` is `True`. + The Sentry Python SDK will capture log records with a level higher than or equal to `sentry_logs_level` as [Sentry structured logs](/platforms/python/logs/). If set to `None`, the SDK won't send records as logs. Only applies when the integration is capturing Sentry logs. Default: `INFO` @@ -182,7 +182,7 @@ sentry_sdk.init( - First, make sure you're on the latest version of the SDK. If you're using the `sentry_sdk.logger` API directly (e.g., `sentry_sdk.logger.info(...)`), logs are sent automatically. If you're using Loguru and want those log records captured as Sentry logs, make sure you have `capture_sentry_logs=True` set on your `LoguruIntegration`. + First, make sure you're on the latest version of the SDK. If you're using the `sentry_sdk.logger` API directly (e.g., `sentry_sdk.logger.info(...)`), logs are sent automatically. If you're using Loguru and want those log records captured as Sentry logs, make sure you have `capture_sentry_logs=True` set on your `LoguruIntegration`. Setting the deprecated `enable_logs=True` also works, but only if `capture_sentry_logs` is left unset on the integration. Your logs could be missing because of the logging level of the logger. The SDK will honor the configured level of each logger. That means that you won't see any `INFO` or `DEBUG` data in Sentry from a logger with the level set to `WARNING`, regardless of how you configure the integration.