Datadog Real User Monitoring (RUM) enables you to visualize and analyze the real-time performance and user journeys of your application’s individual users.
The minimum supported version for the RUM React Native SDK is React Native v0.63.4+. Compatibility with older versions is not guaranteed out-of-the-box.
The RUM React Native SDK supports Expo. For more information, see the Expo documentation.
To install with NPM, run:
npm install @datadog/mobile-react-nativeTo install with Yarn, run:
yarn add @datadog/mobile-react-nativeVersions 1.0.0-rc5 and higher require you to have compileSdkVersion = 31 in the Android application setup, which implies that you should use Build Tools version 31, Android Gradle Plugin version 7, and Gradle version 7 or higher. To modify the versions, change the values in the buildscript.ext block of your application's top-level build.gradle file. Datadog recommends using React Native version 0.67 or higher.
- In the Datadog app, navigate to UX Monitoring > RUM Applications > New Application.
- Choose
react-nativeas the application type. - Provide an application name to generate a unique Datadog application ID and client token.
{{< img src="real_user_monitoring/react_native/image_reactnative.png" alt="Create a RUM application in Datadog workflow" style="width:90%;">}}
To ensure the safety of your data, you must use a client token. If you used only Datadog API keys to configure the @datadog/mobile-react-native library, they would be exposed client-side in the React Native application's code.
For more information about setting up a client token, see the Client Token documentation.
{{< site-region region="us" >}}
import {
DdSdkReactNative,
DdSdkReactNativeConfiguration
} from '@datadog/mobile-react-native';
const config = new DdSdkReactNativeConfiguration(
'<CLIENT_TOKEN>',
'<ENVIRONMENT_NAME>',
'<RUM_APPLICATION_ID>',
true, // track User interactions (e.g.: Tap on buttons).
true, // track XHR Resources
true // track Errors
);
config.site = 'US1';
// Optional: enable or disable native crash reports
config.nativeCrashReportEnabled = true;
// Optional: sample RUM sessions (here, 80% of session will be sent to Datadog. Default = 100%)
config.sessionSamplingRate = 80;
// Optional: sample tracing integrations for network calls between your app and your backend (here, 80% of calls to your instrumented backend will be linked from the RUM view to the APM view. Default = 20%)
// You need to specify the hosts of your backends to enable tracing with these backends
config.resourceTracingSamplingRate = 80;
config.firstPartyHosts = ['example.com']; // matches 'example.com' and subdomains like 'api.example.com'
// Optional: set the reported service name (by default, it'll use the package name / bundleIdentifier of your Android / iOS app respectively)
config.serviceName = 'com.example.reactnative';
// Optional: let the SDK print internal logs (above or equal to the provided level. Default = undefined (meaning no logs))
config.verbosity = SdkVerbosity.WARN;
await DdSdkReactNative.initialize(config);
// Once SDK is initialized you need to setup view tracking to be able to see data in the RUM Dashboard.{{< /site-region >}}
{{< site-region region="us3" >}}
import {
DdSdkReactNative,
DdSdkReactNativeConfiguration
} from '@datadog/mobile-react-native';
const config = new DdSdkReactNativeConfiguration(
'<CLIENT_TOKEN>',
'<ENVIRONMENT_NAME>',
'<RUM_APPLICATION_ID>',
true, // track User interactions (e.g.: Tap on buttons).
true, // track XHR Resources
true // track Errors
);
config.site = 'US3';
// Optional: enable or disable native crash reports
config.nativeCrashReportEnabled = true;
// Optional: sample RUM sessions (here, 80% of session will be sent to Datadog. Default = 100%)
config.sessionSamplingRate = 80;
// Optional: sample tracing integrations for network calls between your app and your backend (here, 80% of calls to your instrumented backend will be linked from the RUM view to the APM view. Default = 20%)
// You need to specify the hosts of your backends to enable tracing with these backends
config.resourceTracingSamplingRate = 80;
config.firstPartyHosts = ['example.com']; // matches 'example.com' and subdomains like 'api.example.com'
await DdSdkReactNative.initialize(config);
// Once SDK is initialized you need to setup view tracking to be able to see data in the RUM Dashboard.{{< /site-region >}}
{{< site-region region="us5" >}}
import {
DdSdkReactNative,
DdSdkReactNativeConfiguration
} from '@datadog/mobile-react-native';
const config = new DdSdkReactNativeConfiguration(
'<CLIENT_TOKEN>',
'<ENVIRONMENT_NAME>',
'<RUM_APPLICATION_ID>',
true, // track User interactions (e.g.: Tap on buttons).
true, // track XHR Resources
true // track Errors
);
config.site = 'US5';
// Optional: enable or disable native crash reports
config.nativeCrashReportEnabled = true;
// Optional: sample RUM sessions (here, 80% of session will be sent to Datadog. Default = 100%)
config.sessionSamplingRate = 80;
// Optional: sample tracing integrations for network calls between your app and your backend (here, 80% of calls to your instrumented backend will be linked from the RUM view to the APM view. Default = 20%)
// You need to specify the hosts of your backends to enable tracing with these backends
config.resourceTracingSamplingRate = 80;
config.firstPartyHosts = ['example.com']; // matches 'example.com' and subdomains like 'api.example.com'
await DdSdkReactNative.initialize(config);
// Once SDK is initialized you need to setup view tracking to be able to see data in the RUM Dashboard.{{< /site-region >}}
{{< site-region region="eu" >}}
import {
DdSdkReactNative,
DdSdkReactNativeConfiguration
} from '@datadog/mobile-react-native';
const config = new DdSdkReactNativeConfiguration(
'<CLIENT_TOKEN>',
'<ENVIRONMENT_NAME>',
'<RUM_APPLICATION_ID>',
true, // track User interactions (e.g.: Tap on buttons).
true, // track XHR Resources
true // track Errors
);
config.site = 'EU1';
// Optional: enable or disable native crash reports
config.nativeCrashReportEnabled = true;
// Optional: sample RUM sessions (here, 80% of session will be sent to Datadog. Default = 100%)
config.sessionSamplingRate = 80;
// Optional: sample tracing integrations for network calls between your app and your backend (here, 80% of calls to your instrumented backend will be linked from the RUM view to the APM view. Default = 20%)
// You need to specify the hosts of your backends to enable tracing with these backends
config.resourceTracingSamplingRate = 80;
config.firstPartyHosts = ['example.com']; // matches 'example.com' and subdomains like 'api.example.com'
await DdSdkReactNative.initialize(config);
// Once SDK is initialized you need to setup view tracking to be able to see data in the RUM Dashboard.{{< /site-region >}}
{{< site-region region="gov" >}}
import {
DdSdkReactNative,
DdSdkReactNativeConfiguration
} from '@datadog/mobile-react-native';
const config = new DdSdkReactNativeConfiguration(
'<CLIENT_TOKEN>',
'<ENVIRONMENT_NAME>',
'<RUM_APPLICATION_ID>',
true, // track User interactions (e.g.: Tap on buttons).
true, // track XHR Resources
true // track Errors
);
config.site = 'US1_FED';
// Optional: enable or disable native crash reports
config.nativeCrashReportEnabled = true;
// Optional: sample RUM sessions (here, 80% of session will be sent to Datadog. Default = 100%)
config.sessionSamplingRate = 80;
// Optional: sample tracing integrations for network calls between your app and your backend (here, 80% of calls to your instrumented backend will be linked from the RUM view to the APM view. Default = 20%)
// You need to specify the hosts of your backends to enable tracing with these backends
config.resourceTracingSamplingRate = 80;
config.firstPartyHosts = ['example.com']; // matches 'example.com' and subdomains like 'api.example.com'
await DdSdkReactNative.initialize(config);
// Once SDK is initialized you need to setup view tracking to be able to see data in the RUM Dashboard.{{< /site-region >}}
If user interactions tracking is enabled as in the code example above, the SDK traverses up the hierarchy of components starting from the component that received a tap, looking for dd-action-name property. Once found, it is used as a name for the action reported.
Alternatively, you can use the accessibilityLabel element property to give the tap action a name; otherwise, the element type is reported. You can check the sample app for usage examples.
Because React Native offers a wide range of libraries to create screen navigation, only manual view tracking is supported by default. To see RUM sessions populate in Datadog, you need to implement view tracking.
You can manually start and stop a view using the following startView() and stopView methods.
import {
DdSdkReactNative,
DdSdkReactNativeConfiguration,
DdLogs,
DdRum
} from '@datadog/mobile-react-native';
// Start a view with a unique view identifier, a custom view url, and an object to attach additional attributes to the view
DdRum.startView(
'<view-key>',
'/view/url',
{ 'custom.foo': 'something' },
Date.now()
);
// Stops a previously started view with the same unique view identifier, and an object to attach additional attributes to the view
DdRum.stopView('<view-key>', { 'custom.bar': 42 }, Date.now());Use one of Datadog's integrations to automatically track views for the following libraries:
- If you use the
react-native-navigationlibrary, then add the@datadog/mobile-react-native-navigationpackage and follow the setup instructions. - If you use the
react-navigationlibrary, then add the@datadog/mobile-react-navigationpackage and follow the setup instructions.
You can attach user information to all RUM events to get more detailed information from your RUM sessions.
For user-specific information, use the following code wherever you want in your app (after the SDK has been initialized). The id, name, and email attributes are built into Datadog, and you can add other attributes that makes sense for your app.
DdSdkReactNative.setUser({
id: '1337',
name: 'John Smith',
email: '[email protected]',
type: 'premium'
});If you want to clear the user information (for example, when the user signs out), you can do so by passing an empty object, as follows:
DdSdkReactNative.setUser({});You can also keep global attributes to track information about a specific session, such as A/B testing configuration, ad campaign origin, or cart status.
DdSdkReactNative.setAttributes({
profile_mode: 'wall',
chat_enabled: true,
campaign_origin: 'example_ad_network'
});If automatic instrumentation doesn't suit your needs, you can manually create RUM Events and Logs:
import {
DdSdkReactNative,
DdSdkReactNativeConfiguration,
DdLogs,
DdRum
} from '@datadog/mobile-react-native';
// Initialize the SDK
const config = new DdSdkReactNativeConfiguration(
'<CLIENT_TOKEN>',
'<ENVIRONMENT_NAME>',
'<RUM_APPLICATION_ID>',
true, // track User interactions (e.g.: Tap on buttons)
true, // track XHR Resources
true // track Errors
);
DdSdkReactNative.initialize(config);
// Send logs (use the debug, info, warn or error methods)
DdLogs.debug('Lorem ipsum dolor sit amet…', {});
DdLogs.info('Lorem ipsum dolor sit amet…', {});
DdLogs.warn('Lorem ipsum dolor sit amet…', {});
DdLogs.error('Lorem ipsum dolor sit amet…', {});
// Track RUM Views manually
DdRum.startView('<view-key>', 'View Url', {}, Date.now());
//…
DdRum.stopView('<view-key>', { custom: 42 }, Date.now());
// Track RUM Actions manually
DdRum.addAction('TAP', 'button name', {}, Date.now());
// or in case of continuous action
DdRum.startAction('TAP', 'button name', {}, Date.now());
// to stop action above
DdRum.stopAction({}, Date.now());
// Add custom timings
DdRum.addTiming('<timing-name>');
// Track RUM Errors manually
DdRum.addError('<message>', 'source', '<stacktrace>', {}, Date.now());
// Track RUM Resource manually
DdRum.startResource(
'<res-key>',
'GET',
'http://www.example.com/api/v1/test',
{},
Date.now()
);
//…
DdRum.stopResource('<res-key>', 200, 'xhr', (size = 1337), {}, Date.now());
// Send spans manually
const spanId = await DdTrace.startSpan('foo', { custom: 42 }, Date.now());
//...
DdTrace.finishSpan(spanId, { custom: 21 }, Date.now());Resource tracking is able to provide the following timings:
First Byte: The time between the scheduled request and the first byte of the response. This includes time for the request preparation on the native level, network latency, and the time it took the server to prepare the response.Download: The time it took to receive a response.
Before data is uploaded to Datadog, it is stored in cleartext in your application's cache directory. This cache folder is protected by Android's Application Sandbox, meaning that on most devices this data can't be read by other applications. However, if the mobile device is rooted, or someone tempers with the Linux kernel, the stored data might become readable.
Before data is uploaded to Datadog, it is stored in cleartext in the cache directory (Library/Caches) of your application sandbox, which can't be read by any other app installed on the device.
While in development mode, your application can submit extra events related to the React Native tooling, such as code transformation errors and requests to a local development server.
To prevent these events from showing in the dashboard, you can disable errors and resources tracking in dev mode using the __DEV__ flag:
const config = new DdSdkReactNativeConfiguration(
CLIENT_TOKEN,
ENVIRONMENT,
APPLICATION_ID,
true,
!__DEV__ /* trackResources will be false in DEV mode, true otherwise */,
!__DEV__ /* trackErrors will be false in DEV mode, true otherwise */,
trackingConsent
)
For more information, see Apache License, v2.0
{{< partial name="whats-next/whats-next.html" >}}