From 62c0dc2d923c720b0807f3f7c9c2aa9f1313ed11 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 25 Aug 2025 21:25:25 +0000
Subject: [PATCH] Add docs for extra fields in Python logging integration

Co-authored-by: aprasad <aprasad@sentry.io>
---
 .../python/integrations/logging/index.mdx     | 29 ++++++++++++++++++
 .../logs/integrations/python.mdx              | 30 +++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/docs/platforms/python/integrations/logging/index.mdx b/docs/platforms/python/integrations/logging/index.mdx
index 63a984ff78abe..a73cedb3c13f2 100644
--- a/docs/platforms/python/integrations/logging/index.mdx
+++ b/docs/platforms/python/integrations/logging/index.mdx
@@ -68,6 +68,35 @@ sentry_sdk.init(
 logging.info("I will be sent to Sentry logs")
 ```
 
+### 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.
+
+```python
+import logging
+import sentry_sdk
+
+sentry_sdk.init(
+    # ...
+    enable_logs=True,
+)
+
+logger = logging.getLogger(__name__)
+
+# Extra fields become top-level searchable attributes
+logger.error(
+    "Payment processing failed", 
+    extra={
+        "user_id": 12345,
+        "transaction_id": "txn_abc123", 
+        "payment_method": "credit_card",
+        "amount": 99.99
+    }
+)
+```
+
+In this example, `user_id`, `transaction_id`, `payment_method`, and `amount` will appear as separate, searchable attributes in the Sentry logs interface, not nested within an `extra` object. You can filter and query logs using these attributes directly, such as `user_id:12345` or `payment_method:credit_card`.
+
 ## Options
 
 To change the default behavior of the logging integration, instantiate the integration manually and pass it to Sentry's `init` function:
diff --git a/platform-includes/logs/integrations/python.mdx b/platform-includes/logs/integrations/python.mdx
index 8cc452660a423..adbd545f11e4f 100644
--- a/platform-includes/logs/integrations/python.mdx
+++ b/platform-includes/logs/integrations/python.mdx
@@ -22,6 +22,36 @@ my_logger.info('But info events will be sent to Sentry logs. my_value=%s', my_va
 
 By default, the logging integration sends `INFO`-level logs and higher to Sentry logs. You can set a different threshold via the `LoggingIntegration`'s `sentry_logs_level` parameter. However, regardless of the `sentry_logs_level` setting, the SDK only sends logs if they are at or above the logger's level.
 
+#### Extra Fields as Searchable Attributes
+
+When using the standard library logging with Sentry logs, any fields provided in the `extra` dictionary are automatically promoted to top-level attributes on the log entry, making them searchable and filterable in the Sentry UI.
+
+```python
+import sentry_sdk
+import logging
+
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    enable_logs=True,
+)
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+# Extra fields become searchable attributes
+logger.info(
+    "User action completed",
+    extra={
+        "user_id": 12345,
+        "action": "purchase",
+        "item_count": 3,
+        "total_amount": 29.97
+    }
+)
+```
+
+In this example, `user_id`, `action`, `item_count`, and `total_amount` will appear as separate, searchable attributes in the Sentry logs interface. You can filter logs using these attributes directly, such as `user_id:12345` or `action:purchase`.
+
 ```python
 import sentry_sdk
 import logging