feat(js): Document new performance APIs

[AbhiPrasad]

resolves getsentry/sentry-javascript#8724

Motivation

Documents the new performance APIs under the custom instrumentation section.

In the future we'll want to revamp both the automatic and custom instrumentation sections, but for now this is a good starting point.

The APIs are detailed in the RFC about the new performance API, and were introduced in getsentry/sentry-javascript#8803

Details

Sentry.startActiveSpan automatically wraps a callback with a span and makes that span the active span for the execution context of the callback. The callback can be async or sync, and can return arbitrary values.

Sentry.startSpan just creates a span, but does not wrap it in a callback. It needs to be explicitly set on the scope just like Sentry.startTransaction.

const result = Sentry.startActiveSpan({ name: importantThing }, async () => {
  await someWork();
  return Sentry.startActiveSpan({ op: 'db', name: 'query-stuff' }, () => expensiveQuery());
});
// result === expensiveQuery() 

Under the hood these methods will create a transaction or span depending on if there is already an active span on the scope.

[vercel]

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

Name	Status	Preview	Comments	Updated (UTC)
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 31, 2023 7:37pm

[Lms24]

LGTM generally, just had some minor comments.

Side note/no action required as too late: I'm only now realizing that startActiveSpan to me conveys that we only start a span but don't finish it after running the callback. Super sorry for not bringing this up earlier! But it's also not the end of the world.

[Lms24]

l: should we shop op as well here or do we consider this not necessary for custom instrumentation?

[AbhiPrasad]

op is optional so I didn't include it. We need to go back and expand documentation on it, but that can happen later on.

[Lms24]

WDYT about

Suggested change

	## Start Transaction
	## [Deprecated] Start Transaction

or something similar that discourages folks from usingstartTransaction?

We probably need to make this JS-specific though so maybe throwing in a note/alert might also work

[AbhiPrasad]

I don't necessarily want to deprecate this method for now, but once we're more comfortable with the API we can come back and adjust.

[Lms24]

l: Is there a reason why this note is different to the Node version? I'd prefer the Node version as it explicitly names the APIs.

[AbhiPrasad]

nope, I just forgot lol

good call!

[AbhiPrasad]

I'm only now realizing that startActiveSpan to me conveys that we only start a span but don't finish it after running the callback

Yeah I thought about this too, but the UX of just not having to think about span finish meant that it kinda just got included with the name. We can alias the name to something else in a future version if users get confused, we have room to move here.

[mydea]

m: Should we mention/explain when/why span is undefined? May not be entirely clear from the outside why this may be unset and why I need to guard here.

[AbhiPrasad]

yup, ill add a note