Project: Simplified Performance API

Project board

See our project board to track this initiative across all SDKs

Description

At the time of Sentry's initial performance product development, OpenTelemetry was in the nascent stages of its lifecycle and was not yet optimized for our requirements. Nevertheless, we maintained similarities in our data models and paradigms with OpenTelemetry. Since then, OpenTelemetry has significantly matured, passed the test of time, and has been generally available (GA) for over a year. It now boasts an extensive ecosystem of integrations spanning multiple technologies, including databases, queues, and protocols.

This maturity means that now is the time for us to rework our Performance Monitoring API to better align with the simpler design of the OTel API. This way, our users will no longer be exposed to Sentry's internal concepts like hubs, scopes and transactions (as a means to combine and batch spans).

👩‍💻 User Stories

As a developer, I want the SDK to offer an easy-to-use API to manually instrument code paths and propagate context where manual instrumentation is impossible, to avoid observability gaps.
As Sentry, we want to make this switch without requiring changes to downstream services.

RFC

https://github.com/getsentry/rfcs/pull/101

https://github.com/getsentry/rfcs/blob/main/text/0101-revamping-the-sdk-performance-api.md

Tasklist

Steps to take for implementing API:

Add span.setName method (span.name is alias for span.description, description should still be serialized and sent with the span payload for now).
Follow the RFC and add top level span creation methods (we recommend Sentry.startActiveSpan and Sentry.startSpan). SDK authors can also add their own methods as appropriate for their SDK, the key is having top level methods that create spans. These span creator methods should require name as a required key in the span context passed in. The important requirement of all span creator methods is that they only reference and operate on spans.
Add top level method for Sentry.setMeasurement
Update performance docs to use new APIs.

### RFC Work
- [ ] https://github.com/getsentry/rfcs/pull/101
- [ ] https://github.com/getsentry/rfcs/pull/113
- [ ] https://github.com/getsentry/rfcs/issues/114

### Web Frontend SDKs
- [ ] https://github.com/getsentry/sentry-javascript/issues/8724

### Web Backend SDKs
- [ ] PHP SDK
- [ ] https://github.com/getsentry/sentry-python/issues/2345
- [ ] Ruby SDK
- [ ] Go SDK
- [ ] Java SDK
- [ ] .NET SDK

### Mobile SDKs
- [ ] Cocoa SDK
- [ ] Android SDK
- [ ] Flutter SDK
- [ ] React Native SDK

FAQ

### Why do we want users not longer have to think about transactions/hubs/scopes? Because they are an implementation detail of Sentry's SDK. Transactions on one had are a bit more front and center but for a user to achieve a simple measurement (Span) we shouldn't require them to understand all these concepts. We internally need to abstract away this complexity and let the user measure what they want simple as e.g.: `startSpan`/`finishSpan` and/or `trace` callback function. ### Why OTEL - or - How we want to use OTEL? Today the OTEL setup is unnecessarily complex and it feels like either you have to use Sentry or use OTEL - The end result has to be that there is only one way and to achieve the highest possible instrumentation we have to use OTEL underneath to cover all integrations possible. ### How do we make sure that the user always gets a measurement? At any point in time - we want to ensure whenever the user measures something - it ends up in Sentry. Specific example even if today there is no ongoing transaction we create one under the hood and send it to Sentry.

getsentry / team-sdks