Skip to content

Commit 2af3888

Browse files
supervacuussupervacuus
authored
Merge branch 'main' into fix/android/id_java_kotlin_frames_tombstone
2 parents 35e1010 + 62b579c commit 2af3888

File tree

302 files changed

+10733
-1787
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

302 files changed

+10733
-1787
lines changed

‎.claude/skills/create-java-pr/SKILL.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
name: create-java-pr
3+
description: Create a pull request in sentry-java. Use when asked to "create pr", "prepare pr", "prep pr", "open pr", "ready for pr", "prepare for review", "finalize changes". Handles branch creation, code formatting, API dump, committing, pushing, PR creation, changelog, and stacked PRs.
4+
---
5+
6+
# Create Pull Request (sentry-java)
7+
8+
Prepare local changes and create a pull request for the sentry-java repo.
9+
10+
**Required reading:** Before proceeding, read `.cursor/rules/pr.mdc` for the full PR and stacked PR workflow details. That file is the source of truth for PR conventions, stack comment format, branch naming, and merge strategy.
11+
12+
## Step 0: Determine PR Type
13+
14+
Ask the user (or infer from context) whether this is:
15+
16+
- **Standalone PR** — a regular PR targeting `main`. Follow Steps 1–6 as written.
17+
- **First PR of a new stack** — ask for a topic name (e.g. "Global Attributes"). Create a collection branch from `main`, then branch the first PR off it. The first PR targets the collection branch.
18+
- **Next PR in an existing stack** — identify the previous stack branch and topic. This PR targets the previous stack branch.
19+
20+
If the user mentions "stack", "stacked PR", or provides a topic name with a number (e.g. `[Topic 2]`), treat it as a stacked PR. See `.cursor/rules/pr.mdc` § "Stacked PRs" for full details.
21+
22+
## Step 1: Ensure Feature Branch
23+
24+
```bash
25+
git branch --show-current
26+
```
27+
28+
If on `main` or `master`, create and switch to a new branch:
29+
30+
```bash
31+
git checkout -b <type>/<short-description>
32+
```
33+
34+
Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`, etc. matching the commit type conventions.
35+
36+
**For stacked PRs:** For the first PR in a new stack, first create and push the collection branch (see `.cursor/rules/pr.mdc` § "Creating the Collection Branch"), then branch the PR off it. For subsequent PRs, branch off the previous stack branch. Use the naming conventions from `.cursor/rules/pr.mdc` § "Branch Naming".
37+
38+
**CRITICAL: Never merge, fast-forward, or push commits into the collection branch.** It stays at its initial position until the user merges stack PRs through GitHub. Updating it will auto-merge and destroy the entire PR stack.
39+
40+
## Step 2: Format Code and Regenerate API Files
41+
42+
```bash
43+
./gradlew spotlessApply apiDump
44+
```
45+
46+
This is **required** before every PR in this repo. It formats all Java/Kotlin code via Spotless and regenerates the `.api` binary compatibility files.
47+
48+
If the command fails, diagnose and fix the issue before continuing.
49+
50+
## Step 3: Commit Changes
51+
52+
Check for uncommitted changes:
53+
54+
```bash
55+
git status --porcelain
56+
```
57+
58+
If there are uncommitted changes, invoke the `sentry-skills:commit` skill to stage and commit them following Sentry conventions.
59+
60+
**Important:** When staging, ignore changes that are only relevant for local testing and should not be part of the PR. Common examples:
61+
62+
| Ignore Pattern | Reason |
63+
|---|---|
64+
| Hardcoded booleans flipped for testing | Local debug toggles |
65+
| Sample app config changes (`sentry-samples/`) | Local testing configuration |
66+
| `.env` or credentials files | Secrets |
67+
68+
Restore these files before committing:
69+
70+
```bash
71+
git checkout -- <file-to-restore>
72+
```
73+
74+
## Step 4: Push the Branch
75+
76+
```bash
77+
git push -u origin HEAD
78+
```
79+
80+
If the push fails due to diverged history, ask the user how to proceed rather than force-pushing.
81+
82+
## Step 5: Create PR
83+
84+
Invoke the `sentry-skills:create-pr` skill to create a draft PR. When providing the PR body, use the repo's PR template structure from `.github/pull_request_template.md`:
85+
86+
```
87+
## :scroll: Description
88+
<Describe the changes in detail>
89+
90+
## :bulb: Motivation and Context
91+
<Why is this change required? What problem does it solve?>
92+
93+
## :green_heart: How did you test it?
94+
<Describe how you tested>
95+
96+
## :pencil: Checklist
97+
- [ ] I added GH Issue ID _&_ Linear ID
98+
- [ ] I added tests to verify the changes.
99+
- [ ] No new PII added or SDK only sends newly added PII if `sendDefaultPII` is enabled.
100+
- [ ] I updated the docs if needed.
101+
- [ ] I updated the wizard if needed.
102+
- [ ] Review from the native team if needed.
103+
- [ ] No breaking change or entry added to the changelog.
104+
- [ ] No breaking change for hybrid SDKs or communicated to hybrid SDKs.
105+
106+
## :crystal_ball: Next steps
107+
```
108+
109+
Fill in each section based on the changes being PR'd. Check any checklist items that apply.
110+
111+
**For stacked PRs:**
112+
113+
- Pass `--base <previous-stack-branch>` so the PR targets the previous branch (first PR in a stack targets the collection branch).
114+
- Use the stacked PR title format: `<type>(<scope>): [<Topic> <N>] <Subject>` (see `.cursor/rules/pr.mdc` § "PR Title Naming").
115+
- Include the stack list at the top of the PR body, before the `## :scroll: Description` section (see `.cursor/rules/pr.mdc` § "Stack List in PR Description" for the format).
116+
- Add a merge method reminder at the very end of the PR body (see `.cursor/rules/pr.mdc` § "Stack List in PR Description" for the exact text). This only applies to stack PRs, not the collection branch PR.
117+
118+
Then continue to Step 5.5 (stacked PRs only) or Step 6.
119+
120+
## Step 5.5: Update Stack List on All PRs (stacked PRs only)
121+
122+
Skip this step for standalone PRs.
123+
124+
After creating the PR, update the PR description on **every other PR in the stack — including the collection branch PR** — so all PRs have the same up-to-date stack list. Follow the format and commands in `.cursor/rules/pr.mdc` § "Stack List in PR Description".
125+
126+
**Important:** When updating PR bodies, never use shell redirects (`>`, `>>`) or pipes (`|`) or compound commands (`&&`). These create compound shell expressions that won't match permission patterns. Instead:
127+
- Use `gh pr view <NUMBER> --json body --jq '.body'` to get the body (output returned directly)
128+
- Use the `Write` tool to save it to a temp file
129+
- Use the `Edit` tool to modify the temp file
130+
- Use `gh pr edit <NUMBER> --body-file /tmp/pr-body.md` to update
131+
132+
## Step 6: Update Changelog
133+
134+
First, determine whether a changelog entry is needed. **Skip this step** (and go straight to "No changelog needed" below) if the changes are not user-facing, for example:
135+
136+
- Test-only changes (new tests, test refactors, test fixtures)
137+
- CI/CD or build configuration changes
138+
- Documentation-only changes
139+
- Code comments or formatting-only changes
140+
- Internal refactors with no behavior change visible to SDK users
141+
- Sample app changes
142+
143+
If unsure, ask the user.
144+
145+
### If changelog is needed
146+
147+
Add an entry to `CHANGELOG.md` under the `## Unreleased` section.
148+
149+
#### Determine the subsection
150+
151+
| Change Type | Subsection |
152+
|---|---|
153+
| New feature | `### Features` |
154+
| Bug fix | `### Fixes` |
155+
| Refactoring, internal cleanup | `### Internal` |
156+
| Dependency update | `### Dependencies` |
157+
158+
Create the subsection under `## Unreleased` if it does not already exist.
159+
160+
#### Entry format
161+
162+
```markdown
163+
- <Short description of the change> ([#<PR_NUMBER>](https://github.com/getsentry/sentry-java/pull/<PR_NUMBER>))
164+
```
165+
166+
Use the PR number returned by `sentry-skills:create-pr`. Match the style of existing entries — sentence case, ending with the PR link, no trailing period.
167+
168+
#### Commit and push
169+
170+
Stage `CHANGELOG.md`, commit with message `changelog`, and push:
171+
172+
```bash
173+
git add CHANGELOG.md
174+
git commit -m "changelog"
175+
git push
176+
```
177+
178+
### No changelog needed
179+
180+
If no changelog entry is needed, add `#skip-changelog` to the PR description to disable the changelog CI check:
181+
182+
1. Get the current body: `gh pr view <PR_NUMBER> --json body --jq '.body'`
183+
2. Use the `Write` tool to save the output to `/tmp/pr-body.md`, appending `\n#skip-changelog\n` at the end
184+
3. Update: `gh pr edit <PR_NUMBER> --body-file /tmp/pr-body.md`

‎.craft.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ targets:
4848
maven:io.sentry:sentry-opentelemetry-agentless-spring:
4949
maven:io.sentry:sentry-opentelemetry-bootstrap:
5050
maven:io.sentry:sentry-opentelemetry-core:
51+
# maven:io.sentry:sentry-opentelemetry-otlp:
52+
# maven:io.sentry:sentry-opentelemetry-otlp-spring:
5153
maven:io.sentry:sentry-apollo:
5254
maven:io.sentry:sentry-jdbc:
5355
maven:io.sentry:sentry-graphql:

‎.cursor/rules/api.mdc‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
alwaysApply: false
3+
description: Public API surface, binary compatibility, and common classes to modify
4+
---
5+
# Java SDK Public API
6+
7+
## API Compatibility
8+
9+
Public API is tracked via `.api` files generated by the [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator) Gradle plugin. Each module has its own file at `<module>/api/<module>.api`.
10+
11+
- **Never edit `.api` files manually.** Run `./gradlew apiDump` to regenerate them.
12+
- `./gradlew check` validates current code against `.api` files and fails on unintended changes.
13+
- `@ApiStatus.Internal` marks classes/methods as internal — they still appear in `.api` files but are not part of the public contract.
14+
- `@ApiStatus.Experimental` marks API that may change in future versions.
15+
16+
## Key Public API Classes
17+
18+
### Entry Point
19+
20+
`Sentry` (`sentry` module) is the static entry point. Most public API methods on `Sentry` delegate to `getCurrentScopes()`. When adding a new method to `Sentry`, it typically calls through to `IScopes`.
21+
22+
### Interfaces
23+
24+
| Interface | Description |
25+
|-----------|-------------|
26+
| `IScope` | Single scope — holds data (tags, extras, breadcrumbs, attributes, user, contexts, etc.) |
27+
| `IScopes` | Multi-scope container — manages global, isolation, and current scope; delegates capture calls to `SentryClient` |
28+
| `ISpan` | Performance span — timing, tags, data, measurements |
29+
| `ITransaction` | Top-level transaction — extends `ISpan` |
30+
31+
### Configuration
32+
33+
`SentryOptions` is the base configuration class. Platform-specific subclasses:
34+
- `SentryAndroidOptions` — Android-specific options
35+
- Integration modules may add their own (e.g. `SentrySpringProperties`)
36+
37+
New features must be **opt-in by default** — add a getter/setter pair to the appropriate options class.
38+
39+
### Internal Classes (Not Public API)
40+
41+
| Class | Description |
42+
|-------|-------------|
43+
| `SentryClient` | Sends events/envelopes to Sentry — receives captured data from `Scopes` |
44+
| `SentryEnvelope` / `SentryEnvelopeItem` | Low-level envelope serialization |
45+
| `Scope` | Concrete implementation of `IScope` |
46+
| `Scopes` | Concrete implementation of `IScopes` |
47+
48+
## Adding New Public API
49+
50+
When adding a new method that users can call (e.g. a new scope operation), these classes typically need changes:
51+
52+
### Interfaces and Static API
53+
1. `IScope` — add the method signature
54+
2. `IScopes` — add the method signature (usually delegates to a scope)
55+
3. `Sentry` — add static method that calls `getCurrentScopes()`
56+
57+
### Implementations
58+
4. `Scope` — actual implementation with data storage
59+
5. `Scopes` — delegates to the appropriate scope (global, isolation, or current based on `defaultScopeType`)
60+
6. `CombinedScopeView` — defines how the three scope types combine for reads (merge, first-wins, or specific scope)
61+
62+
### No-Op and Adapter Classes
63+
7. `NoOpScope` — no-op stub for `IScope`
64+
8. `NoOpScopes` — no-op stub for `IScopes`
65+
9. `ScopesAdapter` — delegates to `Sentry` static API
66+
10. `HubAdapter` — deprecated bridge from old `IHub` API
67+
11. `HubScopesWrapper` — wraps `IScopes` as `IHub`
68+
69+
### Serialization (if the data is sent to Sentry)
70+
12. Add serialization/deserialization in the relevant data class or create a new one implementing `JsonSerializable` and `JsonDeserializer`
71+
72+
### Tests
73+
13. Write tests for all implementations, especially `Scope`, `Scopes`, `SentryTest`, and any new data classes
74+
14. No-op classes typically don't need separate tests unless they have non-trivial logic
75+
76+
## Protocol / Data Model Classes
77+
78+
Classes in the `io.sentry.protocol` package represent the Sentry event protocol. They implement `JsonSerializable` for serialization and have a companion `Deserializer` class implementing `JsonDeserializer`. When adding new fields to protocol classes, update both serialization and deserialization.
79+
80+
## Namespaced APIs
81+
82+
Newer features are namespaced under `Sentry.<feature>()` rather than added directly to `Sentry`. Each namespaced API has an interface, implementation, and no-op. Examples:
83+
84+
- `Sentry.logger()` → `ILoggerApi` / `LoggerApi` / `NoOpLoggerApi` (structured logging, `io.sentry.logger` package)
85+
- `Sentry.metrics()` → `IMetricsApi` / `MetricsApi` / `NoOpMetricsApi` (metrics)
86+
87+
Options for namespaced features are similarly nested under `SentryOptions`, e.g. `SentryOptions.getMetrics()`, `SentryOptions.getLogs()`.
88+
89+
These APIs may share infrastructure like the type system (`SentryAttributeType.inferFrom()`) — changes to shared components (e.g. attribute types) may require updates across multiple namespaced APIs.

‎.cursor/rules/opentelemetry.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ The Sentry Java SDK provides comprehensive OpenTelemetry integration through mul
1414
- `sentry-opentelemetry-agentless-spring`: Spring-specific agentless integration
1515
- `sentry-opentelemetry-bootstrap`: Classes that go into the bootstrap classloader when the agent is used. For agentless they are simply used in the applications classloader.
1616
- `sentry-opentelemetry-agentcustomization`: Classes that help wire up Sentry in OpenTelemetry. These land in the agent classloader when the agent is used. For agentless they are simply used in the application classloader.
17+
- `sentry-opentelemetry-otlp`: Classes for using OpenTelemetry to send spans to Sentry using the OTLP endpoint and have Sentry use OpenTelemetry trace and span id.
18+
- `sentry-opentelemetry-otlp-spring`: Spring Boot convenience module that includes `sentry-opentelemetry-otlp` and the OpenTelemetry Spring Boot starter as transitive dependencies.
1719

1820
## Advantages over using Sentry without OpenTelemetry
1921

@@ -86,3 +88,10 @@ After creating the transaction with child spans `SentrySpanExporter` uses Sentry
8688
## Troubleshooting
8789

8890
To debug forking of `Scopes`, we added a reference to `parent` `Scopes` and a `creator` String to store the reason why `Scopes` were created or forked.
91+
92+
# OTLP
93+
When using `sentry-opentelemetry-otlp`, Sentry only loads trace ID and span ID from OpenTelemetry `Context` (via `OpenTelemetryOtlpEventProcessor`). Sentry does not rely on OpenTelemetry `Context` for scope storage and propagation, instead relying on its `DefaultScopesStorage`.
94+
It is common to keep Performance in Sentry SDK disabled since that part is taken over by OpenTelemetry.
95+
The `sentry-opentelemetry-otlp` module is not connected to the other `sentry-opentelemetry-*` modules but instead intended only when the goal is to run OpenTelemetry for creating spans and Sentry for other products like errors, logs, metrics etc.
96+
The `sentry-opentelemetry-otlp-spring` module wraps `sentry-opentelemetry-otlp` and includes the OpenTelemetry Spring Boot starter for easier setup in Spring Boot applications.
97+
The OTLP module does not easily work with the OpenTelemetry agent as it would require customizing the agent.JAR in order to get the propagator loaded.

0 commit comments

Comments
 (0)