Create cursor rules file explaining our OpenTelemetry integration #4588
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
adinauer
requested review from
romtsn,
stefanosiano and
markushi
as code owners
This stack of pull requests is managed by Graphite. Learn more about stacking. |
7 tasks
adinauer
force-pushed
the
08-01-create_cursor_rules_file_explaining_our_opentelemetry_integration
branch
from
a7e9275 to
46df387
Compare
adinauer
force-pushed
the
feat/offline-behaviour-rules-file
branch
from
0dc4ab2 to
1e939de
Compare
adinauer
changed the base branch from
feat/offline-behaviour-rules-file
to
graphite-base/4588
adinauer
force-pushed
the
08-01-create_cursor_rules_file_explaining_our_opentelemetry_integration
branch
from
46df387 to
85c39af
Compare
adinauer
force-pushed
the
graphite-base/4588
branch
from
1e939de to
6fc8adc
Compare
adinauer
force-pushed
the
08-01-create_cursor_rules_file_explaining_our_opentelemetry_integration
branch
from
85c39af to
af58c24
Compare
lcian
approved these changes
Aug 1, 2025
lbloder
reviewed
Aug 1, 2025
|
|
||
| **Manual Integration**: | ||
| While it's possible to manually wire up all the required classes to make Sentry and OpenTelemetry work together, we do not recommend this. | ||
| It is instead preferrable to go through `SentryAutoConfigurationCustomizerProvider` so the Sentry SDK has a place to manage required classes and update it when changes are needed. |
There was a problem hiding this comment.
"to use" instead of "go through"?
| - Determine whether any Sentry OpenTelemetry integration is present | ||
| - Determine which mode to use and in turn which Sentry auto instrumentation to suppress | ||
|
|
||
| Reflection is used to search for `io.sentry.opentelemetry.OtelContextScopesStorage` and use it instead of `DefaultScopesStorage` when a Sentry OpenTelemetry integration is present at runtime. `IScopesStorage` is used to store Sentry `Scopes` instances. `DefaultScopesStorage` will use a thread local variable to store the current threads `Scopes` whereas `OtelContextScopesStorage` makes use of OpenTelemetry SDKs `Context`. Sentry OpenTelemetry integrations configure OpenTelemetry to use `SentryOtelThreadLocalStorage` to customize restoring of the previous `Context`. |
There was a problem hiding this comment.
Suggested change
| Reflection is used to search for `io.sentry.opentelemetry.OtelContextScopesStorage` and use it instead of `DefaultScopesStorage` when a Sentry OpenTelemetry integration is present at runtime. `IScopesStorage` is used to store Sentry `Scopes` instances. `DefaultScopesStorage` will use a thread local variable to store the current threads `Scopes` whereas `OtelContextScopesStorage` makes use of OpenTelemetry SDKs `Context`. Sentry OpenTelemetry integrations configure OpenTelemetry to use `SentryOtelThreadLocalStorage` to customize restoring of the previous `Context`. | |
| Reflection is used to search for `io.sentry.opentelemetry.OtelContextScopesStorage` and use it instead of `DefaultScopesStorage` when a Sentry OpenTelemetry integration is present at runtime. `IScopesStorage` is used to store Sentry `Scopes` instances. `DefaultScopesStorage` will use a thread local variable to store the current threads' `Scopes` whereas `OtelContextScopesStorage` makes use of OpenTelemetry SDKs `Context`. Sentry OpenTelemetry integrations configure OpenTelemetry to use `SentryOtelThreadLocalStorage` to customize restoring of the previous `Context`. |
|
|
||
| Reflection is used to search for `io.sentry.opentelemetry.OtelContextScopesStorage` and use it instead of `DefaultScopesStorage` when a Sentry OpenTelemetry integration is present at runtime. `IScopesStorage` is used to store Sentry `Scopes` instances. `DefaultScopesStorage` will use a thread local variable to store the current threads `Scopes` whereas `OtelContextScopesStorage` makes use of OpenTelemetry SDKs `Context`. Sentry OpenTelemetry integrations configure OpenTelemetry to use `SentryOtelThreadLocalStorage` to customize restoring of the previous `Context`. | ||
|
|
||
| OpenTelemetry SDK makes use of `io.opentelemetry.context.Scope` in `try` with statements that call `close` when a code block is finished. Without customization, it would refuse to restore the previous `Context` onto the `ThreadLocal` if the current state of the `ThreadLocal` isn't the same as the one this scope was created for. Sentry changes this behaviour in `SentryScopeImpl` to restore the previous `Context` onto the `ThreadLocal` even if an inner `io.opentelemetry.context.Scope` wasn't properly cleaned up. Our thinking here is to prefer returning to a clean state as opposed to propagating the problem. The unclean state could happen, if `io.opentelemetry.context.Scope` isn't closed, e.g. when forgetting to put it in a `try` with statement and not calling `close` (e.g. not putting it in a `finally` block in that case). |
There was a problem hiding this comment.
Maybe like this? try-with-resources is the name used in the oracle docs.
Suggested change
| OpenTelemetry SDK makes use of `io.opentelemetry.context.Scope` in `try` with statements that call `close` when a code block is finished. Without customization, it would refuse to restore the previous `Context` onto the `ThreadLocal` if the current state of the `ThreadLocal` isn't the same as the one this scope was created for. Sentry changes this behaviour in `SentryScopeImpl` to restore the previous `Context` onto the `ThreadLocal` even if an inner `io.opentelemetry.context.Scope` wasn't properly cleaned up. Our thinking here is to prefer returning to a clean state as opposed to propagating the problem. The unclean state could happen, if `io.opentelemetry.context.Scope` isn't closed, e.g. when forgetting to put it in a `try` with statement and not calling `close` (e.g. not putting it in a `finally` block in that case). | |
| OpenTelemetry SDK makes use of `io.opentelemetry.context.Scope` in `try-with-resources` statements that call `close` when a code block is finished. Without customization, it would refuse to restore the previous `Context` onto the `ThreadLocal` if the current state of the `ThreadLocal` isn't the same as the one this scope was created for. Sentry changes this behaviour in `SentryScopeImpl` to restore the previous `Context` onto the `ThreadLocal` even if an inner `io.opentelemetry.context.Scope` wasn't properly cleaned up. Our thinking here is to prefer returning to a clean state as opposed to propagating the problem. The unclean state could happen, if `io.opentelemetry.context.Scope` isn't closed, e.g. when forgetting to put it in a `try-with-resources` statement and not calling `close` (e.g. not putting it in a `finally` block in that case). |
| The Sentry Java SDK provides comprehensive OpenTelemetry integration through multiple modules: | ||
|
|
||
| - `sentry-opentelemetry-core`: Core OpenTelemetry integration functionality | ||
| - `sentry-opentelemetry-agent`: Agent-based integration for automatic instrumentation |
There was a problem hiding this comment.
Maybe call it Java Agent here as well?
| @@ -0,0 +1,84 @@ | |||
| # Java SDK OpenTelemetry Integration | |||
There was a problem hiding this comment.
Do we need to add the header for cursor here? See https://docs.cursor.com/en/context/rules#rule-anatomy
| - `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. | ||
| - `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. | ||
|
|
||
| ## Advantages over using Sentry without OpenTelemetry |
There was a problem hiding this comment.
Is this section relevant for an AI?
| @@ -0,0 +1,84 @@ | |||
| # Java SDK OpenTelemetry Integration | |||
There was a problem hiding this comment.
Also, maybe double-check against the best practices for rules in the cursor docs: https://docs.cursor.com/en/context/rules#best-practices
|
|
||
| **Agent-based integration**: | ||
| - Automatic instrumentation via Java agent | ||
| - Can be added to any JAR when starting, no extra dependencies or code changes required. Just add the agent to the `java` command. |
There was a problem hiding this comment.
Maybe an example command would be helpful here.
| @@ -0,0 +1,84 @@ | |||
| # Java SDK OpenTelemetry Integration | |||
There was a problem hiding this comment.
What is the purpose of this ruleset?
To give cursor guidance on how to develop in this module? Or to let cursor know how to use this module in a project?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
#skip-changelog
📜 Description
💡 Motivation and Context
💚 How did you test it?
📝 Checklist
sendDefaultPIIis enabled.🔮 Next steps