Performance Tracing (Beta)
Overview
Embrace’s Performance Tracing solution gives you visibility into any app operation you’d like to track, including duration, success rate, and any contextual metadata collected at runtime that helps debug the root cause of your mobile app's performance issues. With our tool, you can quickly spot any bottlenecks in your app’s architecture, pinpoint areas you need to troubleshoot with high precision, and ultimately deliver a truly optimized user experience.
Feature Support
- We recommend using the latest Embrace React Native SDK version for the most up-to-date API. Even though Performance Tracing is enabled in Embrace React Native versions 4.1.0 and above.
The Embrace Performance Tracing API allows you to:
- Create record data for past operations.
- To record past operations, you can specify the start and end times of your spans that you might have captured already.
- Add child spans to a parent span to track sub-operations within an operation.
- Attach attributes and span events to each span to give them further context
- Attributes allow you to specify string key-value pairs that can be useful for filtering, grouping, and deriving custom metrics
- Span events represent a point in time of the execution of the span and they can also have attributes
There are no limits on the duration of a span as long as the app is running.
There are also no limits to the number of child spans you can have per trace, provided the total number of spans do not exceed the per-session maximum.
Limits
Type | Limit |
---|---|
Max number of spans per session | 500 |
Max number of attributes per span | 50 |
Max number of events per span | 10 |
Max number of attributes per event | 10 |
Length of attribute keys | 50 characters |
Length of attribute values | 200 characters |
Length of Span names | 50 characters |
Length of Event names | 100 characters |
If you exceed the listed limits, the operation with the limit-exceeding call will fail. See the API documentation for details.
Naming Conventions
- Span Names are case-sensitive and are a max of 50 characters.
- Key Names are case-sensitive, have a max of 50 characters, and are alphanumeric ASCII characters
The emb-
and emb.
prefixes are reserved for internal Embrace span and attribute names, respectively. You should never create a span or attribute key name with emb-
and emb.
prefixes
Adding Performance Traces To Your App
To use this feature:
- Ensure you're using Embrace React Native version 4.1.0 or greater.
- Instrument your app using the reference guide in this section to start adding traces to your operations.
- See the traces in the Traces section of the Embrace dashboard.
Install the component
yarn add @embrace-io/react-native-spans
npm install @embrace-io/react-native-spans
API Usage Examples
Create a Span
// create a trace by creating its root span
// recording will not behind until the span has been started
import { startSpan } from '@embrace-io/react-native-spans';
// startSpan: (name: string, parentSpanId?: string, startTimeMs?:number) => Promise<boolean | string>;
const spanId = await startSpan("parentname")
Create a Span that started in the past (or future)
// create a trace by creating its root span
import { startSpan } from '@embrace-io/react-native-spans';
// startSpan: (name: string, parentSpanId?: string, startTimeMs?:number) => Promise<boolean | string>;
const startTimeMs = new Date().getTime()
const spanId = await startSpan("parentname", undefined, startTimeMs)
Add an Attribute to a Span
// add an attribute to a specific span
import { startSpan, stopSpan, addSpanAttributeToSpan } from '@embrace-io/react-native-spans';
// addSpanAttributeToSpan: (spanId: string, key: string, value: string) => Promise<boolean>;
// Starting a span
const spanId = await startSpan("parentname")
// Adding an attribute to a specific span
addSpanAttributeToSpan(spanId, "myKey", "value")
stopSpan(spanId)
Add an Event to a Span
// add an event to a specific span
import { startSpan, stopSpan, addSpanEventToSpan } from '@embrace-io/react-native-spans';
// addSpanEventToSpan: (spanId: string, name: string, timeStampMs: number,
// attributes?: Attributes) => Promise<boolean>;
// Starting a span
const spanId = await startSpan("parentname")
// Adding an event to a specific span
const attributes = {
"key1":"value1",
"key2":"value2",
"key3":"value3",
}
addSpanEventToSpan(spanId, "eventName", new Date().getTime(), attributes)
stopSpan(spanId)
Stop Span For Operation That Ended Earlier
// Stopping a specific span
import { startSpan, stopSpan } from '@embrace-io/react-native-spans';
// stopSpan: (spanId: string, errorCode?: SPAN_ERROR_CODES, endTimeMs?:number) => Promise<boolean>;
// type SPAN_ERROR_CODES = 'None' | 'Failure' | 'UserAbandon' | 'Unknown';
// Starting a span
const spanId = await startSpan("parentname")
// Do something
const endTimeMs = new Date().getTime()
// Stopping the span
stopSpan(spanId, "Failure", endTimeMs)
Stop Span For an Operation That Failed
// Stopping a specific span
import { startSpan, stopSpan } from '@embrace-io/react-native-spans';
// stopSpan: (spanId: string, errorCode?: SPAN_ERROR_CODES, endTimeMs?:number) => Promise<boolean>;
// type SPAN_ERROR_CODES = 'None' | 'Failure' | 'UserAbandon' | 'Unknown';
// Starting a span
const spanId = await startSpan("parentname")
try{
// Do something that throw an error
}catch(e){
// Stopping the span with an Error Code
stopSpan(spanId, "Failure")
}