Skip to content

Commit 94b513a

Browse files
Update docs on extra fields as attributes (#14711)
## DESCRIBE YOUR PR This PR updates the Python logging documentation to clarify how `extra` fields are handled by the Sentry SDK. Users were previously confused why `extra` fields weren't visible as a nested object in the Sentry UI. This change explains that fields within the `extra` dictionary are automatically promoted to top-level, searchable attributes on Sentry log entries. Specifically: * Added a "Working with Extra Fields" section to `docs/platforms/python/integrations/logging/index.mdx`. * Added an "Extra Fields as Searchable Attributes" subsection to `platform-includes/logs/integrations/python.mdx`. These updates ensure users understand that they can directly filter and query logs using these attributes (e.g., `user_id:12345`). ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE <!-- Sentry employees and contractors can delete or ignore this section. --> Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --- [Slack Thread](https://sentry.slack.com/archives/C081M1KEQ0L/p1756152479348829?thread_ts=1756152479.348829&cid=C081M1KEQ0L) <a href="https://cursor.com/background-agent?bcId=bc-f0dee11c-f641-4de8-a80a-1ff3bac28351"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/open-in-cursor-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://cursor.com/open-in-cursor-light.svg"> <img alt="Open in Cursor" src="https://cursor.com/open-in-cursor.svg"> </picture> </a> <a href="https://cursor.com/agents?id=bc-f0dee11c-f641-4de8-a80a-1ff3bac28351"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/open-in-web-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://cursor.com/open-in-web-light.svg"> <img alt="Open in Web" src="https://cursor.com/open-in-web.svg"> </picture> </a> Co-authored-by: Cursor Agent <[email protected]>
1 parent ee33323 commit 94b513a

File tree

2 files changed

+59
-0
lines changed
  • docs/platforms/python/integrations/logging
  • platform-includes/logs/integrations

2 files changed

+59
-0
lines changed

docs/platforms/python/integrations/logging/index.mdx

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,35 @@ sentry_sdk.init(
6868
logging.info("I will be sent to Sentry logs")
6969
```
7070

71+
### Working with Extra Fields
72+
73+
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.
74+
75+
```python
76+
import logging
77+
import sentry_sdk
78+
79+
sentry_sdk.init(
80+
# ...
81+
enable_logs=True,
82+
)
83+
84+
logger = logging.getLogger(__name__)
85+
86+
# Extra fields become top-level searchable attributes
87+
logger.error(
88+
"Payment processing failed",
89+
extra={
90+
"user_id": 12345,
91+
"transaction_id": "txn_abc123",
92+
"payment_method": "credit_card",
93+
"amount": 99.99
94+
}
95+
)
96+
```
97+
98+
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`.
99+
71100
## Options
72101

73102
To change the default behavior of the logging integration, instantiate the integration manually and pass it to Sentry's `init` function:

platform-includes/logs/integrations/python.mdx

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,36 @@ my_logger.info('But info events will be sent to Sentry logs. my_value=%s', my_va
2222

2323
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.
2424

25+
#### Extra Fields as Searchable Attributes
26+
27+
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.
28+
29+
```python
30+
import sentry_sdk
31+
import logging
32+
33+
sentry_sdk.init(
34+
dsn="___PUBLIC_DSN___",
35+
enable_logs=True,
36+
)
37+
38+
logger = logging.getLogger(__name__)
39+
logger.setLevel(logging.INFO)
40+
41+
# Extra fields become searchable attributes
42+
logger.info(
43+
"User action completed",
44+
extra={
45+
"user_id": 12345,
46+
"action": "purchase",
47+
"item_count": 3,
48+
"total_amount": 29.97
49+
}
50+
)
51+
```
52+
53+
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`.
54+
2555
```python
2656
import sentry_sdk
2757
import logging

0 commit comments

Comments
 (0)