rfc(feature): SDK Lifecycle Hooks

README.md

@@ -20,6 +20,7 @@ This repository contains RFCs and DACIs. Lost?
 - [0022-response-context](text/0022-response-context.md): Response context
 - [0033-view-hierarchy](text/0033-view-hierarchy.md): View Hierarchy
 - [0027-manual-disabling-of-flaky-tests](text/0027-manual-disabling-of-flaky-tests.md): Processes for manually disabling flaky tests in `sentry` and `getsentry`
+- [00034-sdk-lifecycle](text/0034-sdk-lifecycle-hooks.md): SDK Lifecycle hooks
 - [0036-auto-instrumentation-ui-thread](text/0036-auto-instrumentation-ui-thread.md): auto-instrumentation UI thread
 - [0037-anr-rates](text/0037-anr-rates.md): Calculating accurate ANR rates
 - [0038-scrubbing-sensitive-data](text/0038-scrubbing-sensitive-data.md): Scrubbing sensitive data - how to improve

text/0034-sdk-lifecycle-hooks.md

@@ -0,0 +1,135 @@
+- Start Date: 2022-11-03
+- RFC Type: feature
+- RFC PR: [https://github.com/getsentry/rfcs/pull/34](https://github.com/getsentry/rfcs/pull/34)
+- RFC Status: approved
+- RFC Driver: [Abhijeet Prasad](https://github.com/AbhiPrasad)
+
+# Summary
+
+This PR proposes the introduction of lifecycle hooks in the SDK, improving extensibility and usability of SDKs at Sentry.
+
+To test out this RFC, we implemented it in the [JavaScript SDK](https://github.com/getsentry/sentry-javascript/blob/7aa20d04a3d61f30600ed6367ca7151d183a8fc9/packages/types/src/client.ts#L153) with great success, so now we are looking to propose and implement it in the other SDKs.
+
+Lifecyle hooks can be registered on a Sentry client, and allow for integrations to have finely grained control over the event lifecycle in the SDK.
+
+Currently hooks are meant to be completely internal to SDK implementors - but we can re-evaluate this in the future.
+
+```ts
+interface Client {
+ // ...
+
+ on(hookName: string, callback: (...args: unknown) => void) => void;
+
+ emit(hookName: string, ...args: unknown[]) => void;
+
+ // ...
+}
+```
+
+# Motivation
+
+There are three main ways users can extend functionality in the SDKs right now.
+
+At it's current form, the SDK is an event processing pipeline. It takes in some data (an error/message, a span, a profile), turns it into the event, attaches useful context to that event based on the current scope, and then sends that event to Sentry.
+
+```
+| Error | ---> | Event | ---> | EventWithContext | ---> | Envelope | ---> | Transport | ---> | Sentry |
+```
+
+```
+| TransactionStart | ---> | SpanStart | ---> | SpanFinish | ---> | TransactionFinish | --> | Event | ---> | EventWithContext | ---> | Envelope | ---> | Transport | ---> | Sentry |
+```
+
+```
+| Session | ---> | Envelope | ---> | Transport | ---> | Sentry |
+```
+
+The SDKs provide a few ways to extend this pipeline:
+
+1. Event Processors (what Integrations use)
+2. `beforeSend` callback
+3. `beforeBreadcrumb` callback
+
+But these are all top level options in someway, and are part of the unified API as a result. This means that in certain scenarios, they are not granular enough as extension points.
+
+The following are some examples of how sdk hooks can unblock new features and integrations, but not a definitive list:
+
+- Integrations want to add information to spans when they start or finish. This is what [RFC #75 is running into](https://github.com/getsentry/rfcs/pull/75), where they want to add thread information to each span.
+- Integrations want to add information to envelopes before they are sent to Sentry.
+- Integrations want to run code on transaction/span finish (to add additional spans to the transaction, for example).
+- Integrations want to mutate an error on `captureException`
+- Integrations want to override propagation behaviour (extracing/injecting outgoing headers)
+
+# Proposal
+
+SDK hooks live on the client, and are **stateless**. They are called in the order they are registered. SDKs can opt-in to whatever hooks they use, and there can be hooks unique to an SDK.
+
+Hooks are meant to be mostly internal APIs for integration authors, but we can also expose them to SDK users if there is a use case for it.
+
+As hook callbacks are not processed by the client. Data passed into can be mutated, which can have side effects on the event pipeline, and consquences for hooks with async callbacks. As such, we recommend using hooks for synchronous operations only, but SDK authors can choose to implement them as async if they need to.
+
+```ts
+// Example implementation in JavaScript
+
+type HookCallback = (...args: unknown[]): void;
+
+class Client {
+ hooks: {
+ [hookName: string]: HookCallback[];
+ };
+
+ on(hookName: string, callback: HookCallback): void {
+ this.hooks[hookName].push(callback);
+ }
+
+ emit(hookName: string, ...args: unknown[]): void {
+ this.hooks[hookName].forEach(callback => callback(...args));
+ }
+}
+```
+
+For languages that cannot use dynamic strings as hook names, alternate options should be considered. For example, we could use a `Hook` enum, or a `Hook` class with static properties.
+
+The primary hook functions named `on` and `emit` can also change based on implementor SDK. For example, using `addObserver` and `notifyObserver` may work better in the Java and Apple SDKs (since those are the names of the observer pattern in those languages).
+
+Hook callbacks are recommended to be forwards compatible, and forward any arguments they don't use. This allows us to add new arguments to hooks without breaking integrations. For example in Python we should catch and forward extra keyword arguments to the callback.
+
+SDKs are expected to have a common set of hooks, but can also have SDK specific hooks.
+
+## Hooks
+
+These following are a set of example hooks that would unblock some use cases listed above. The names/schema of the hooks are not final, and are meant to be used as a starting point for discussion.
+
+To document and approve new hooks, we will create a new page in the develop docs that lists all the hooks, and what they are used for.
+
+`startTransaction`:
+
+```ts
+on('startTransaction', callback: (transaction: Transaction) => void) => void;
+```
+
+`finishTransaction`:
+
+```ts
+on('finishTransaction', callback: (transaction: Transaction) => void) => void;
+```
+
+`startSpan`:
+
+```ts
+on('startSpan', callback: (span: Span) => void) => void;
+```
+
+`finishSpan`:
+
+```ts
+on('finishSpan', callback: (span: Span) => void) => void;
+```
+
+`beforeEnvelope`:
+
+```ts
+on('beforeEnvelope', callback: (envelope: Envelope) => void) => void;
+```
+
+Other possible hooks inlcude `beforeBreadcrumb`, `beforeSend`, `startSession` and `endSession`.