Performance

Performance monitoring namespace. Provides control over custom traces, screen load markers, and access to captured metrics. All methods are no-op if performance feature is disabled.

import ScaleBun from '@scalebun/react-native';
ScaleBun.performance.<method>(…);

Members#

Reference#

startTrace#

ScaleBun.performance.startTrace(name: string): string | null

Start a custom trace. Returns traceId or null.

stopTrace#

ScaleBun.performance.stopTrace(traceId: string): void

Stop a custom trace by ID.

addTraceSpan#

ScaleBun.performance.addTraceSpan(traceId: string, name: string, durationMs: number, data?: Record<string, unknown>): void

Add a span to an active custom trace.

addTraceMeasurement#

ScaleBun.performance.addTraceMeasurement(traceId: string, name: string, value: number, unit: string): void

Attach a measurement to an active custom trace.

markScreenLoadStart#

ScaleBun.performance.markScreenLoadStart(screenName: string): void

Mark the start of a screen load.

markScreenLoadEnd#

ScaleBun.performance.markScreenLoadEnd(screenName: string): void

Mark the end of a screen load.

setCurrentScreen#

ScaleBun.performance.setCurrentScreen(screenName: string): void

Set the current screen for context correlation.

onNavigationStateChange#

ScaleBun.performance.onNavigationStateChange(state: unknown): void

Forward navigation state changes for auto screen load detection.

isActive#

ScaleBun.performance.isActive(): boolean

Check if performance monitoring is active

sendMetric#

ScaleBun.performance.sendMetric(name: string, value: number, unit?: string, tags?: Record<string, string>): void

Send a raw performance metric through the transport. Used for manual/simulated performance metrics.

Notes#

The performance namespace reports timing — app launch, screen loads, network calls and custom spans. Most of it collects automatically once initialised; the parts worth your attention are the ones that need instrumentation.

Initialise early or under-report launch time#

App-start measurement can only observe what happens after the SDK is running. Initialising late does not produce a wrong number — it produces a flattering one, because the slow part of launch happened before measurement began.

If your launch numbers look better than your users' experience, check where init() sits in your startup sequence before looking anywhere else.

Screen names decide whether the data is usable#

Screen-load reporting groups by name, and two naming mistakes make the whole page useless:

• No names — every load collapses into one row and there is nothing to compare.

• Dynamic names — a name containing an id or a resolved path creates one row per entity, so nothing aggregates.

Use route templates. Setting the navigation reference lets the SDK derive them automatically; failing that, mark boundaries explicitly.

Ordering#

1. 1

   init() as early as your app allows

   Everything here measures from that point.

2. 2

   Set the navigation reference next

   It is what makes screen-load and flow data appear without per-screen work.

3. 3

   Add custom spans for your critical flows

   Checkout, search, sign-in. Automatic capture covers navigation and network; work inside your own functions is invisible unless you span it.

4. 4

   Finish every span you start — in a finally

   An unfinished span never arrives. An early return or a thrown error silently drops the measurement, which is why the cleanup belongs in finally rather than after the happy path.

Limits and edge cases#

• A custom span with a name built from a variable creates a new transaction type per value. Names must be static.

• Sampling applies, so this is a representative set rather than a complete log — do not count anything from it.

• These calls do not throw. A span that failed to record is silent in a release build.

• Platform differences are real: app-start is mobile, Web Vitals are web. The dashboard hides what does not apply rather than showing it empty.

Related#

• Performance SDK guide

• Performance overview