feat(shared): SDK telemetry #2154
Conversation
🦋 Changeset detectedLatest commit: a783aba The changes in this PR will be included in the next version bump. This PR includes changesets to release 12 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
| @@ -0,0 +1,155 @@ | |||
| import 'cross-fetch/polyfill'; | |||
There was a problem hiding this comment.
fetch isn't available in the jsdom jest environment 😢, so adding the polyfill here.
packages/shared/src/telemetry.ts
Outdated
| #scheduleFlush(): void { | ||
| // On the server, we want to flush immediately as we have less guarantees about the lifecycle of the process | ||
| if (typeof window === 'undefined') { | ||
| this.#flush(); | ||
| return; | ||
| } | ||
|
|
||
| const isBufferFull = this.#buffer.length >= this.#config.maxBufferSize; | ||
| if (isBufferFull) { | ||
| // If the buffer is full, flush immediately to make sure we minimize the chance of event loss. | ||
| // Cancel any pending flushes as we're going to flush immediately | ||
| if (this.#pendingFlush) { | ||
| const cancel = typeof cancelIdleCallback !== 'undefined' ? cancelIdleCallback : clearTimeout; | ||
| cancel(this.#pendingFlush); | ||
| } | ||
| this.#flush(); | ||
| return; | ||
| } | ||
|
|
||
| // If we have a pending flush, do nothing | ||
| if (this.#pendingFlush) return; | ||
|
|
||
| if ('requestIdleCallback' in window) { | ||
| this.#pendingFlush = requestIdleCallback(() => { | ||
| this.#flush(); | ||
| }); | ||
| } else { | ||
| // This is not an ideal solution, but it at least waits until the next tick | ||
| this.#pendingFlush = setTimeout(() => { | ||
| this.#flush(); | ||
| }, 0); | ||
| } | ||
| } |
There was a problem hiding this comment.
This was my attempt to implement buffering in a way that mitigates potential data loss. It uses requestIdleCallback to schedule sending events during idle time. When an event is recorded, it schedules a flush during idle, and if the buffer limit is reached it immediately flushes the events.
The scheduling of a flush on every record might be a tad aggressive, but we can tweak later if we want.
packages/shared/src/telemetry.ts
Outdated
| .catch(() => void 0) | ||
| .then(() => { | ||
| this.#buffer = []; | ||
| }) | ||
| .catch(() => void 0); |
There was a problem hiding this comment.
Catch into the void to avoid leaking any errors here. ESLint complained that the chain had to end in a .catch, hence the final .catch as well.
|
|
||
| fetchSpy.mockRestore(); | ||
| }); | ||
| }); |
Yes, good reminder! I'll add this.
Will open a follow-up PR with hooks usage events 👍 |
* feat(clerk-js): Spike out telemetry collection * feat(clerk-js): Add sampling rate and verbose option * feat(shared): Move TelemtryCollector into shared, make it isomorphic * feat(nextjs): Add telemtry collection for authMiddleware * feat(shared): Support passing multiple events to the telemetry endpoint * feat(shared): Abstract fetch into sendEvent * feat(shared): Refactor SDK metadata handling to get accurate value * feat(shared): Update endpoint, don't use no-cors * fix(nextjs): Fix merge conflict * feat(shared): Add batching to the telemetry collector * feat(shared): Add opt-out support for SDK telemetry (#2099) * feat(clerk-js): Add TelemetryCollector instance to backend client (#2134) * chore(repo): Add changeset * fix(shared): Fix tests that rely on fetch * feat(shared): Set production endpoint * feat(clerk-js): Make telemtry public, expose via isomorphicClerk * feat(shared): Add doc on the TelemetryCollector * feat(clerk-js): Support telemetry: false as a way to disable telemetry * chore(shared): Tweak comment * chore(shared): Tweak comment * fix(clerk-sdk-node): Add PACKAGE_ constants for tests * fix(fastify): Define PACKAGE_ constants in test environment * feat(shared): Refactor telemetry instrumentation to rely on helpers * feat(shared): Add telemetry notice * feat(shared): Add postinstall script * chore(shared): Add word * chore(shared): Swallow errors in postinstall * chore(repo): Allow scripts directory in subpaths-workaround * feat(shared): Adjust types to enforce the event structure from event factory methods * chore(shared): Simplify telemetry.record() API
Description
Introduces opt-out telemetry collection from our SDKs by way of a new
TelemetryCollectorclass. Currently, this supports collection both on the client, by way of our core Clerk instance, and on the server, by way of the pre-initialized@clerk/backendclient.Client collection:
Server collection:
The
clerkClientfactory from@clerk/backendnow acceptssdkMetadata, which is passed from each SDK. This metadata is then passed toTelemetryCollectorand included in telemetry events. Currently, collection is only done from development instances.Opting-out
To opt-out, we respect a
CLERK_TELEMETRY_DISABLEenvironment variable. Frameworks with unique environment variable prefixes, such as Next'sNEXT_PUBLIC_will also disable telemetry collection.Docs
Documentation is being prepared here: clerk/clerk-docs#496
Checklist
npm testruns as expected.npm run buildruns as expected.Type of change
Packages affected
@clerk/backend@clerk/chrome-extension@clerk/clerk-js@clerk/clerk-expo@clerk/fastifygatsby-plugin-clerk@clerk/localizations@clerk/nextjs@clerk/clerk-react@clerk/remix@clerk/clerk-sdk-node@clerk/shared@clerk/themes@clerk/typesbuild/tooling/chore