feat(js): Add beforeSendTransaction option

[lobsterkatie]

This adds the new beforeSendTransaction option to the docs, both on the options page and alongside beforeSend in many places in the text. Because you can't selectively turn certain phrases on and off for different platforms, I tried to indicate where I could that it's not universally supported. (Right now, I believe JS is in fact the only platform to support it, though I expect that to change in the near future.) It also does a tiny bit of wordsmithing of the text around the additions, courtesy of @lizokm and @imatwawana.

Note that the one spot where updates haven't been done in this PR is the text of the Filtering page, as it's being worked on separately in #5804. Once the changes there are done, #5838 will add beforeSendTransaction.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
sentry-docs	✅ Ready (Inspect)	Visit Preview	Nov 22, 2022 at 6:10PM (UTC)

[imatwawana]

I've made some overall wording tweaks and left a couple questions.

[imatwawana]

I don't think you need the two sentences starting at "Note" because this is already a page devoted to error events. It's a given that things on this page may not apply to transactions. That kind of caveat only needs to exist on the parent page.

Suggested change

All Sentry SDKs support the `beforeSend` callback method. Once implemented, the method is invoked when the SDK captures an error event, right before sending it to your Sentry account. It receives the event object as a parameter, so you can use that to modify the event's data or drop it completely (by returning `null`) based on your custom logic and the data available on the event, like _tags_, _environment_, _release version_, _error attributes_, and so on. Note that only error and message events pass through `beforeSend`. Tansaction events have a separate method, `beforeSendTransaction`, though it is not yet supported in all SDKs. Learn more about both methods in [Filtering Events](/platform-redirect/?next=/configuration/filtering/).

All Sentry SDKs support the `beforeSend` callback method. Once implemented, the method is invoked when the SDK captures an error event, right before sending it to your Sentry account. It receives the event object as a parameter, so you can use that to modify the event's data or drop it completely (by returning `null`) based on your custom logic and the data available on the event, like _tags_, _environment_, _release version_, _error attributes_, and so on. Learn more in [Filtering Events](/platform-redirect/?next=/configuration/filtering/).

[lobsterkatie]

I disagree. The fact that transactions don't go through beforeSend is a perennial source of confusion for users, which is fair given that a) it's not called beforeSendError, and b) we have a bad habit of using "event" to sometimes mean "error event" and sometimes mean "error or transaction event," a holdover from the days when there were no transaction events, so it's easy to mess up which things apply only to errors and which things apply to all events.

Also, this is 327 lines in, so if you got here by searching beforeSend, or a following a link, you easily might not realize what page you're on, especially since the lefthand sidebar doesn't automatically scroll to show the highlighted section. Check out the screenshot below, where there's only the faintest indication that what we're looking at is specific to error events:

So I think it can't hurt to be extra clear on this point.

[imatwawana]

Is this heading alias from an ancient version of this doc?

Suggested change

	## 3. SDK Filtering: beforeSendTransaction {#1-sdk-filtering-beforesendtransaction}
	## 3. SDK Filtering: beforeSendTransaction {#1-sdk-filtering-beforesendtransaction}

[lobsterkatie]

I have to assume so? IDK, I just went with it, because fixing it really should be a separate PR if we're going to do it.

[lizokm]

Woot! Looking good.

[smeubank]

https://sentry-docs-git-kmclb-add-beforesendtransaction-to-js-options.sentry.dev/platforms/javascript/configuration/options/#before-send-transaction

[lobsterkatie]

Thanks for the suggestions, @imatwawana and @lizokm! I took most of them, and @imatwawana, I tried to answer your questions above. In order to unblock folks working on beforeSendTransaction in other SDKs, I'm going to merge this, but if we need to come back to anything in a future PR, we totally can. (UPDATE: Which I'm already doing, because I didn't actually push the last set of changes based on your edits. 🤦🏻‍♀️)

P.S. Just for the record (since it came up again in this PR), in hopes of preventing us from going back and forth every time I use the phrase "Note that xxxx" (which I'll admit I perhaps do too frequently):

No disrespect intended, but you can't note-comma-that. It's just not grammatical. Either "note" is an interjection (akin to "look" or "see" in the phrases "look, here's the thing" or "see, that's the problem"), in which case it gets a comma, or it's a prepositional verb (akin to "look" or "see" in the phrases "look at the sky" or "see that you do"), in which case it doesn't. But if it's an interjection, you have to be able to get rid of it and still have a full sentence after you've done so. Removing "Note," from, "Note, that xyz is true" just leaves you with "that xyz is true," which clearly isn't a fully-formed sentence. So we can argue the stylistic merits of "Note, xyz is true" vs. "Note that xyz is true" (I gravitate towards the latter, but am open to switching to the former if you think it fits the overall docs style better), but the hybrid doesn't work.

(Other than that, though, I really do appreciate the help tightening up my prose. My brain thinks in many layers of parentheses, and I try to keep it out of my writing, but I know I don't always succeed. So keep 'em coming!)