You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 451a51c
Browse filesBrowse the repository at this point in the historyBrowse files
Each namespaced options class is a `public static final class` inside `SentryOptions` with its own fields, getters/setters, and callbacks (e.g. `BeforeSendLogCallback`, `BeforeSendMetricCallback`).
18
+
Each namespaced options class is a `public static final class` inside `SentryOptions` with its own fields, getters/setters, factories, and callbacks (e.g. `BeforeSendLogCallback`, `BeforeSendMetricCallback`).
16
19
17
-
A typical namespaced options class contains:
18
-
- `enabled` boolean (default `false` for opt-in)
19
-
- `sampleRate` double (if the feature supports sampling)
20
-
- `beforeSend` callback interface (nested inside the options class)
20
+
Do not assume that a namespaced signal needs an aggregate `enabled` field. In particular, Logs and
21
+
Metrics are available through deliberate API calls whenever the SDK is enabled. Their namespaced
22
+
options contain signal-specific behavior such as `beforeSend`, limits, and processor factories. Add
23
+
options such as sampling only when the signal supports them. Automatic capture integrations use
24
+
source-local enable options that default to `false`.
21
25
22
26
To add a new namespaced options class:
23
27
1. Create the `public static final class` inside `SentryOptions` with fields, getters/setters, and any callback interfaces
@@ -47,21 +51,18 @@ The core options class. Add the field (or nested class) with getter/setter here.
47
51
Allows setting options via `sentry.properties` file or system properties. Fields use nullable wrapper types (`@Nullable Boolean`, `@Nullable Double`) since unset means "don't override the default."
`SentryProperties` extends `SentryOptions`, so namespaced options (nested classes) are automatically available as Spring Boot properties without extra code. For example, `SentryOptions.Logs` is automatically mapped to `sentry.logs.enabled` in `application.properties`.
90
+
`SentryProperties` extends `SentryOptions`, so bindable namespaced behavior options are available
91
+
through the `SentryOptions` class hierarchy. Spring-owned integration controls belong to a Spring
92
+
namespace instead. For example, `SentryProperties.Logging.logsEnabled` binds to
93
+
`sentry.logging.logs-enabled` and controls Logs forwarding from the auto-configured Logback
94
+
appender. `sentry.logging.enabled` separately controls whether that appender is installed.
87
95
88
-
No additional code is needed for namespaced options — Spring Boot auto-configuration handles this via property binding on the `SentryOptions` class hierarchy.
96
+
Do not add or restore `sentry.logs.enabled` or `sentry.metrics.enabled`; those aggregate properties
- Add the property (e.g. `"sentry.logs.enabled=true"`) to the existing `resolves all properties` test
100
+
- Add the new property to the existing binding test
92
101
- Assert the value is set on the resolved `SentryProperties` bean
102
+
- Test default, explicit `true`, explicit `false`, and propagation into the owning integration
93
103
- There are three Spring Boot modules with separate test files: `sentry-spring-boot`, `sentry-spring-boot-jakarta`, `sentry-spring-boot-4`
94
104
95
105
### 5. Reading Options at Runtime
96
106
97
-
Features check their options at usage time. For namespaced features the check typically happens in the feature's API class (e.g. `LoggerApi`, `MetricsApi`):
98
-
- Check `options.getLogs().isEnabled()` early and return if disabled
99
-
- Apply sampling via `options.getLogs().getSampleRate()` if applicable
100
-
- Apply `beforeSend` callback in `SentryClient` before sending
107
+
Deliberate APIs such as `LoggerApi` and `MetricsApi` do not check aggregate signal enable flags.
108
+
They capture whenever their scopes are enabled, then apply signal behavior such as sampling and
109
+
`beforeSend`.
110
+
111
+
Automatic integrations must check their source-local opt-in without affecting their existing event
112
+
or breadcrumb paths. Current Logs controls are:
113
+
- Logback: appender `logsEnabled`
114
+
- Log4j2: appender `logsEnabled`
115
+
- JUL: handler `logsEnabled`
116
+
- Spring Boot Logback: `sentry.logging.logs-enabled`
Copy file name to clipboardExpand all lines: .cursor/rules/scopes.mdc
+5-5Lines changed: 5 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -14,8 +14,8 @@ Data itself is stored on `Scope` instances.
14
14
## `Hub`
15
15
16
16
Up until major version 7 of the Java SDK the `IHub` interface was a central part of the SDK.
17
-
In major version 8 we replaced the `IHub` interface with `IScopes`. `IHub` has been deprecated.
18
-
While there is some bridging code in place to allow for easier migration, we are planning to remove it in an upcoming major.
17
+
In major version 8 we replaced the `IHub` interface with `IScopes` and deprecated the Hub compatibility APIs.
18
+
Those compatibility APIs were removed in major version 9.
19
19
20
20
## Scope Types
21
21
@@ -79,7 +79,7 @@ There were several implementations of the `IHub` interface:
79
79
`HubAdapter` has been replaced by `ScopesAdapter`
80
80
`Hub.clone` should be replaced by using `pushScope` or `pushIsolationScope`
81
81
`Sentry.getCurrentHub` has been replaced by `Sentry.getCurrentScopes`
82
-
`Sentry.popScope` has been deprecated. Instead `close` should be called on the `ISentryLifecycleToken` returned e.g. by `pushScope`. This can also be done in a `try-with-resource` block.
82
+
`Sentry.popScope` was deprecated in version 8 and removed in version 9. Instead, `close` should be called on the `ISentryLifecycleToken` returned e.g. by `pushScope`. This can also be done in a `try-with-resources` block.
83
83
84
84
## `globalHubMode`
85
85
The SDK has a `globalHubMode` option which affects forking behaviour of the SDK.
@@ -93,8 +93,8 @@ For JVM Backend applications (servers) we discourage enabling `globalHubMode` si
93
93
If `globalHubMode` is enabled, the SDK avoids forking scopes _implicitly_.
94
94
95
95
This means, retrieving current scopes on a thread where specific scopes do not exist yet for the thread, the root scopes are not forked but returned directly.
96
-
`Sentry.pushScope`, `Sentry.pushIsolationScope` and `Sentry.popScope` are no-ops.
97
-
They are unbalanced API: the caller may never restore the previous scopes, or restore them on a different thread, which would corrupt the globally shared scopes.
96
+
`Sentry.pushScope`and `Sentry.pushIsolationScope` are no-ops and return no-op lifecycle tokens.
97
+
Implicit forking is suppressed because callers could otherwise fail to restore the previous scopes, or restore them on a different thread, which would corrupt the globally shared scopes.
98
98
99
99
`Sentry.withScope` and `Sentry.withIsolationScope` do fork, also when `globalHubMode` is enabled.
100
100
They are balanced by construction and always restore the previous scopes before returning, so they cannot corrupt the shared scopes.
![sentry-junior[bot]](https://avatars.githubusercontent.com/in/2960336?v=4&size=40){kind=avatar}
0 commit comments