Skip to content

Commit 0046a40

Browse files
adinauerclaude
adinauer
and
claude
authored
docs(java): Add scope attributes docs for logs and metrics (#16639)
Add scope attributes sections to Java and Android logs/metrics usage docs, showing how to set attributes on the scope that are automatically included in all logs/metrics. Covers `setAttribute` (with auto type inference), `SentryAttribute` factory methods (for explicit typing), `setAttributes` (for multiple at once), and `removeAttribute`. Examples are consistent across all four platform-includes files (logs/metrics x java/android). Also adds scope attributes references in the default-attributes docs for Java logs and Android/Java metrics. Co-Authored-By: Claude <noreply@anthropic.com> PR Stack in SDK repo: getsentry/sentry-java#5118 (comment) Co-authored-by: Claude <noreply@anthropic.com>
1 parent 5676c9a commit 0046a40

File tree

7 files changed

+256
-0
lines changed

7 files changed

+256
-0
lines changed

‎platform-includes/logs/default-attributes/java.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,7 @@ The Java SDK automatically sets several default attributes on all log entries to
1111
<Include name="logs/default-attributes/user" />
1212

1313
<Include name="logs/default-attributes/integration" />
14+
15+
### Scope Attributes
16+
17+
Any attributes set on the current scope via `Sentry.setAttribute()` or `Sentry.setAttributes()` are automatically included on all log entries. See [Usage](#usage) above for details.

‎platform-includes/logs/usage/android.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,3 +65,59 @@ Sentry.logger().log(
6565
"param1"
6666
)
6767
```
68+
69+
### Scope Attributes
70+
71+
You can set attributes on the scope that will be automatically included in all log entries captured within that scope. This is useful for attaching contextual information like request IDs or user properties that should appear on every log.
72+
73+
```java {tabTitle: Java}
74+
import io.sentry.Sentry;
75+
import io.sentry.SentryAttribute;
76+
import io.sentry.SentryAttributes;
77+
78+
// Set a single attribute with automatic type inference
79+
Sentry.setAttribute("request.id", "abc-123");
80+
81+
// Or use a factory method to set the type explicitly
82+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150));
83+
84+
// Set multiple attributes at once
85+
Sentry.setAttributes(SentryAttributes.of(
86+
SentryAttribute.stringAttribute("tenant", "acme-corp"),
87+
SentryAttribute.booleanAttribute("is_admin", true)
88+
));
89+
90+
// All subsequent logs will include these attributes
91+
Sentry.logger().info("Processing request");
92+
93+
// Remove an attribute when it's no longer relevant
94+
Sentry.removeAttribute("request.id");
95+
```
96+
97+
```kotlin {tabTitle: Kotlin}
98+
import io.sentry.Sentry
99+
import io.sentry.SentryAttribute
100+
import io.sentry.SentryAttributes
101+
102+
// Set a single attribute with automatic type inference
103+
Sentry.setAttribute("request.id", "abc-123")
104+
105+
// Or use a factory method to set the type explicitly
106+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150))
107+
108+
// Set multiple attributes at once
109+
Sentry.setAttributes(SentryAttributes.of(
110+
SentryAttribute.stringAttribute("tenant", "acme-corp"),
111+
SentryAttribute.booleanAttribute("is_admin", true)
112+
))
113+
114+
// All subsequent logs will include these attributes
115+
Sentry.logger().info("Processing request")
116+
117+
// Remove an attribute when it's no longer relevant
118+
Sentry.removeAttribute("request.id")
119+
```
120+
121+
Attribute types are inferred automatically from the value: `String` maps to `string`, `Boolean` to `boolean`, integer types (`Integer`, `Long`, `Short`, `Byte`, `BigInteger`, `AtomicInteger`, `AtomicLong`) to `integer`, floating-point types (`Float`, `Double`, `BigDecimal`) to `double`, and `Collection` or array types to `array`. You can also use typed factory methods like `SentryAttribute.stringAttribute()` to set the type explicitly.
122+
123+
Attributes passed directly to a log call override scope attributes with the same key.

‎platform-includes/logs/usage/java.mdx‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,74 @@ Sentry.logger().log(
6666
)
6767
```
6868

69+
### Scope Attributes
70+
71+
You can set attributes on the scope that will be automatically included in all log entries captured within that scope. This is useful for attaching contextual information like request IDs or user properties that should appear on every log.
72+
73+
```java {tabTitle: Java}
74+
import io.sentry.Sentry;
75+
import io.sentry.ScopeType;
76+
import io.sentry.SentryAttribute;
77+
import io.sentry.SentryAttributes;
78+
79+
// Set an attribute on the global scope so it applies to all logs
80+
Sentry.configureScope(ScopeType.GLOBAL, scope -> {
81+
scope.setAttribute("region", "us-east-1");
82+
});
83+
84+
// Set a single attribute with automatic type inference
85+
Sentry.setAttribute("request.id", "abc-123");
86+
87+
// Or use a factory method to set the type explicitly
88+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150));
89+
90+
// Set multiple attributes at once
91+
Sentry.setAttributes(SentryAttributes.of(
92+
SentryAttribute.stringAttribute("tenant", "acme-corp"),
93+
SentryAttribute.booleanAttribute("is_admin", true)
94+
));
95+
96+
// All subsequent logs will include these attributes
97+
Sentry.logger().info("Processing request");
98+
99+
// Remove an attribute when it's no longer relevant
100+
Sentry.removeAttribute("request.id");
101+
```
102+
103+
```kotlin {tabTitle: Kotlin}
104+
import io.sentry.Sentry
105+
import io.sentry.ScopeType
106+
import io.sentry.SentryAttribute
107+
import io.sentry.SentryAttributes
108+
109+
// Set an attribute on the global scope so it applies to all logs
110+
Sentry.configureScope(ScopeType.GLOBAL) { scope ->
111+
scope.setAttribute("region", "us-east-1")
112+
}
113+
114+
// Set a single attribute with automatic type inference
115+
Sentry.setAttribute("request.id", "abc-123")
116+
117+
// Or use a factory method to set the type explicitly
118+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150))
119+
120+
// Set multiple attributes at once
121+
Sentry.setAttributes(SentryAttributes.of(
122+
SentryAttribute.stringAttribute("tenant", "acme-corp"),
123+
SentryAttribute.booleanAttribute("is_admin", true)
124+
))
125+
126+
// All subsequent logs will include these attributes
127+
Sentry.logger().info("Processing request")
128+
129+
// Remove an attribute when it's no longer relevant
130+
Sentry.removeAttribute("request.id")
131+
```
132+
133+
Attribute types are inferred automatically from the value: `String` maps to `string`, `Boolean` to `boolean`, integer types (`Integer`, `Long`, `Short`, `Byte`, `BigInteger`, `AtomicInteger`, `AtomicLong`) to `integer`, floating-point types (`Float`, `Double`, `BigDecimal`) to `double`, and `Collection` or array types to `array`. You can also use typed factory methods like `SentryAttribute.stringAttribute()` to set the type explicitly.
134+
135+
Attributes passed directly to a log call override scope attributes with the same key.
136+
69137
<PlatformSection supported={["java.spring-boot"]}>
70138
It is also possible to use Logback and Spring Boot together to have logs going through Logback sent to Sentry. Take a look at the <PlatformLink to="/logging-frameworks/">Logging Framework Integrations</PlatformLink> page.
71139
</PlatformSection>

‎platform-includes/metrics/default-attributes/android.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,7 @@ If user information is available in the current scope, the following attributes
1818
If replay information is available in the current scope, the following attributes are added to the log:
1919

2020
- `sentry.replay_id`: The ID of the replay.
21+
22+
### Scope Attributes
23+
24+
Any attributes set on the current scope via `Sentry.setAttribute()` or `Sentry.setAttributes()` are automatically included on all metrics. See [Usage](#usage) above for details.

‎platform-includes/metrics/default-attributes/java.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,7 @@ If user information is available in the current scope, the following attributes
1818
The SDK will attach the following:
1919

2020
- `server.address`: The address of the server that sent the metric. Equivalent to `server_name` that gets attached to Sentry errors.
21+
22+
### Scope Attributes
23+
24+
Any attributes set on the current scope via `Sentry.setAttribute()` or `Sentry.setAttributes()` are automatically included on all metrics. See [Usage](#usage) above for details.

‎platform-includes/metrics/usage/android.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,60 @@ Sentry.metrics().distribution(
108108
)
109109
```
110110

111+
### Scope Attributes
112+
113+
You can set attributes on the scope that will be automatically included in all metrics captured within that scope. This is useful for attaching contextual information that should appear on every metric.
114+
115+
```java {tabTitle: Java}
116+
import io.sentry.Sentry;
117+
import io.sentry.SentryAttribute;
118+
import io.sentry.SentryAttributes;
119+
120+
// Set a single attribute with automatic type inference
121+
Sentry.setAttribute("request.id", "abc-123");
122+
123+
// Or use a factory method to set the type explicitly
124+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150));
125+
126+
// Set multiple attributes at once
127+
Sentry.setAttributes(SentryAttributes.of(
128+
SentryAttribute.stringAttribute("service", "checkout"),
129+
SentryAttribute.booleanAttribute("canary", false)
130+
));
131+
132+
// All subsequent metrics will include these attributes
133+
Sentry.metrics().count("order_placed", 1.0);
134+
135+
// Remove an attribute when it's no longer relevant
136+
Sentry.removeAttribute("canary");
137+
```
138+
139+
```kotlin {tabTitle: Kotlin}
140+
import io.sentry.Sentry
141+
import io.sentry.SentryAttribute
142+
import io.sentry.SentryAttributes
143+
144+
// Set a single attribute with automatic type inference
145+
Sentry.setAttribute("request.id", "abc-123")
146+
147+
// Or use a factory method to set the type explicitly
148+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150))
149+
150+
// Set multiple attributes at once
151+
Sentry.setAttributes(SentryAttributes.of(
152+
SentryAttribute.stringAttribute("service", "checkout"),
153+
SentryAttribute.booleanAttribute("canary", false)
154+
))
155+
156+
// All subsequent metrics will include these attributes
157+
Sentry.metrics().count("order_placed", 1.0)
158+
159+
// Remove an attribute when it's no longer relevant
160+
Sentry.removeAttribute("canary")
161+
```
162+
163+
Attributes passed directly to a metric call override scope attributes with the same key.
164+
111165
### Specifying Units
112166

113167
For `gauge` and `distribution` metrics, you can specify a unit using the `unit` option. This helps Sentry display the metric value in a human-readable format. `MetricsUnit` offers constants for units supported by Sentry. Sending in custom units is not supported.

‎platform-includes/metrics/usage/java.mdx‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,72 @@ Sentry.metrics().distribution(
108108
)
109109
```
110110

111+
### Scope Attributes
112+
113+
You can set attributes on the scope that will be automatically included in all metrics captured within that scope. This is useful for attaching contextual information that should appear on every metric.
114+
115+
```java {tabTitle: Java}
116+
import io.sentry.Sentry;
117+
import io.sentry.ScopeType;
118+
import io.sentry.SentryAttribute;
119+
import io.sentry.SentryAttributes;
120+
121+
// Set an attribute on the global scope so it applies to all metrics
122+
Sentry.configureScope(ScopeType.GLOBAL, scope -> {
123+
scope.setAttribute("region", "us-east-1");
124+
});
125+
126+
// Set a single attribute with automatic type inference
127+
Sentry.setAttribute("request.id", "abc-123");
128+
129+
// Or use a factory method to set the type explicitly
130+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150));
131+
132+
// Set multiple attributes at once
133+
Sentry.setAttributes(SentryAttributes.of(
134+
SentryAttribute.stringAttribute("service", "checkout"),
135+
SentryAttribute.booleanAttribute("canary", false)
136+
));
137+
138+
// All subsequent metrics will include these attributes
139+
Sentry.metrics().count("order_placed", 1.0);
140+
141+
// Remove an attribute when it's no longer relevant
142+
Sentry.removeAttribute("canary");
143+
```
144+
145+
```kotlin {tabTitle: Kotlin}
146+
import io.sentry.Sentry
147+
import io.sentry.ScopeType
148+
import io.sentry.SentryAttribute
149+
import io.sentry.SentryAttributes
150+
151+
// Set an attribute on the global scope so it applies to all metrics
152+
Sentry.configureScope(ScopeType.GLOBAL) { scope ->
153+
scope.setAttribute("region", "us-east-1")
154+
}
155+
156+
// Set a single attribute with automatic type inference
157+
Sentry.setAttribute("request.id", "abc-123")
158+
159+
// Or use a factory method to set the type explicitly
160+
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150))
161+
162+
// Set multiple attributes at once
163+
Sentry.setAttributes(SentryAttributes.of(
164+
SentryAttribute.stringAttribute("service", "checkout"),
165+
SentryAttribute.booleanAttribute("canary", false)
166+
))
167+
168+
// All subsequent metrics will include these attributes
169+
Sentry.metrics().count("order_placed", 1.0)
170+
171+
// Remove an attribute when it's no longer relevant
172+
Sentry.removeAttribute("canary")
173+
```
174+
175+
Attributes passed directly to a metric call override scope attributes with the same key.
176+
111177
### Specifying Units
112178

113179
For `gauge` and `distribution` metrics, you can specify a unit using the `unit` option. This helps Sentry display the metric value in a human-readable format. `MetricsUnit` offers constants for units supported by Sentry. Sending in custom units is not supported.

0 commit comments

Comments
 (0)