feat(instrumentation): Use versioned global for tracing helper #26167
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
### Background and Problem
Hi :) We maintain the official Sentry SDK and would love to have first class support for Prisma instrumentation. We are currently depending on a specific v5 version of the `@prisma/instrumentation` package as a dependency of our Node.js SDK (`@sentry/node`).
With the release of Prisma v6 we examined applications crash that used Prisma v6 in combination with our SDK with our Prisma instrumentation enabled. The reason for that was that the `TracingHelper`'s interface was changed with Prisma v6, renaming a method (`createEngineSpan` -> `dispatchEngineSpans`) and the Sentry SDK registered the version 5 `TracingHelper`, which caused Prisma to call a method on it that doesn't exist.
We would love for our SDK to be compatible with multiple Prisma versions, and we assume other telemetry vendors would do so too! This PR doesn't necessarily fix the crashing, but it introduces a non-breaking mechanism to facilitate registering tracing helpers for specific versions of Prisma in a forwards compatible way.
### Changes
Currently, Prisma picks up whatever tracing helper is on `globalThis.PRISMA_INSTRUMENTATION` when an instrumentation library like `@prisma/instrumentation` put a helper there. There are no checks whether the helper is compatible with the current prisma version or not.
Because doing checks for compatibility is annoying, this PR updates Prisma to pick up the tracing helpers from a versioned field instead. The field is named `V${prismaMajorVersion}_PRISMA_INSTRUMENTATION`. This allows instrumentation libraries to register tracing helpers for specific versions of Prisma, without introducing any sort of incompatibilities.
To make this change actually non-breaking, we still need to read from `globalThis.PRISMA_INSTRUMENTATION`, for example when people would upgrade `@prisma/client` (where the reading happens) but not `@prisma/instrumentation` (where the writing happens).
aqrln
approved these changes
Jan 30, 2025
Member
aqrln
left a comment
aqrln
left a comment
There was a problem hiding this comment.
This looks great to me, thank you!
Member
|
Hey @lforst, do you want us to make a patch release with this change so you could make use of it right away? |
Contributor
Author
|
@aqrln all good. Thank you! This was more like a thing to ensure that things don't blow up in the future. We ended up adding something to our SDK that patches the helper to ensure that it doesn't crash on older versions. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Background and Problem
Hi :) We maintain the official Sentry SDK and would love to have first class support for Prisma instrumentation. We are currently depending on a specific v5 version of the
@prisma/instrumentationpackage as a dependency of our Node.js SDK (@sentry/node).With the release of Prisma v6 we examined applications crash that used Prisma v6 in combination with our SDK with our Prisma instrumentation enabled. The reason for that was that the
TracingHelper's interface was changed with Prisma v6, renaming a method (createEngineSpan->dispatchEngineSpans) and the Sentry SDK registered the version 5TracingHelper, which caused Prisma to call a method on it that doesn't exist.We would love for our SDK to be compatible with multiple Prisma versions, and we assume other telemetry vendors would do so too! This PR doesn't necessarily fix the crashing, but it introduces a non-breaking mechanism to facilitate registering tracing helpers for specific versions of Prisma in a forwards compatible way.
Changes
Currently, Prisma picks up whatever tracing helper is on
globalThis.PRISMA_INSTRUMENTATIONwhen an instrumentation library like@prisma/instrumentationput a helper there. There are no checks whether the helper is compatible with the current prisma version or not.Because doing checks for compatibility is annoying, this PR updates Prisma to pick up the tracing helpers from a versioned field instead. The field is named
V${prismaMajorVersion}_PRISMA_INSTRUMENTATION. This allows instrumentation libraries to register tracing helpers for specific versions of Prisma, without introducing any sort of incompatibilities.To make this change actually non-breaking, we still need to read from
globalThis.PRISMA_INSTRUMENTATION, for example when people would upgrade@prisma/client(where the reading happens) but not@prisma/instrumentation(where the writing happens). In the next major, I would recommend dropping the fallback to reduce the risk of Prisma crashing when libraries put incompatible helpers on the fallback global.