@dynatrace/react-native-plugin

Dynatrace React Native Plugin

The Dynatrace React Native plugin helps to auto-instrument your React Native app with Dynatrace OneAgent for Android and iOS and provides a TypeScript bridge to add manual instrumentation. It is compatible with raw, ejected React Native projects. It does not support Expo.

Currently this plugin is available as an early access version. If you want to test it, please sign up for the EAP.

Supported features

The following features are currently supported:

• Auto-instrumentation using OneAgent for Android and iOS
  • User actions for AppStart and native controls
  • Web requests
  • Crashes
• React-native instrumentation
  • User actions for touches Touchables and lifecycle events such as render(), didMount() and didUpdate()
  • Reporting React Native Errors
• Manual instrumentation
  • Typescript bindings to add manual instrumentation

Requirements

• React Native >= 0.48
• React Native Instrumentation => ES6 Classes
• For Android users: Minimum SDK version 15
• For iOS users: Minimum iOS 6

Quick Setup

1. Eject your app
2. Install plugin
3. Register Dynatrace transformer
4. Download dynatrace.config
5. Run auto instrumentation
6. Build and run your app

Advanced topics

• Manual instrumentation
• Debug Output
• Documentation
• How does Dynatrace determine the user action name?
• Known issues
• Changelog
  
  

Quick Setup

1. Eject your app

• If your app is not yet ejected do it now by calling react-native eject. This generates the Android and iOS folders that are required by the plugin.

2. Install the plugin

• Install the plugin by calling react-native install @dynatrace/react-native-plugin.
  • Implicitely this will also call react-native link @dynatrace/react-native-plugin which will automatically add the iOS agent pod to your iOS project.
  • An installation script registers a script in package.json that will be used for auto-instrumentation later on.

Troubleshooting

• Expo-Kit only: the installation script does not get triggered automatically. You can call it manually by running node ./node_modules/@dynatrace/react-native-plugin/scripts/install.js
• If for some reason (e.g. seperate native projects) react-native link does not work as expected, you can manually add the iOS agent to your project

Manually add the iOS agent to your project (with CocoaPods support)

insert the following in your Podfile:

pod 'react-native-dynatrace', :path => '../node_modules/@dynatrace/react-native-plugin'

Manually add the iOS agent to your project (without CocoaPods support)

• Open your project in Xcode
• Run open node_modules/@dynatrace/react-native-plugin/ios
• Drag DynatraceRNBridge.xcodeproj into your Libraries group
• Select your main project in the navigator to bring up settings
• Under Build Phases expand the Link Binary With Libraries header
• Scroll down and click the + to add a library
• Find and add libRNDynatrace.a under the Workspace group
• ⌘+B

3. Register the Dynatrace transform

Depending on your react native version you will need to use a different way to register the transformer. If you don't know it, you can use react-native --version to get it.

RN >= 0.59

In your projects root, either create or extend metro.config.js so it contains the transformer.babelTransformerPath property:

module.exports = {
  transformer: {
    babelTransformerPath: require.resolve('@dynatrace/react-native-plugin/lib/dynatrace-transformer')
  }
};

RN >= 0.57, < 0.59

Add this to your rn-cli.config.js (make one if you don't have one already):

module.exports = {
  transformer: {
    babelTransformerPath: require.resolve('@dynatrace/react-native-plugin/lib/dynatrace-transformer')
  }
}

RN < 0.57

Add this to your rn-cli.config.js (make one if you don't have one already):

module.exports = {
  getTransformModulePath() {
    return require.resolve('@dynatrace/react-native-plugin/lib/dynatrace-transformer');
  },
  getSourceExts() {
    return ['ts', 'tsx'];
  }
}

4. Download dynatrace.config

Define a mobile app in Dynatrace and open the Mobile app instrumentation settings. The React Native plugin uses the same configuration format as the Cordova plugin, so you can select "Cordova". Ignore steps 1 and 2 and move directly to step 3 - "Download dynatrace.config".

Place the file into your project root directory next to app.json. If the file is not available the auto instrumentation will not work. Example of a dynatrace.config file:

<NATIVEAGENT>
    <DTXApplicationID>Application ID</DTXApplicationID>
    <DTXAgentEnvironment>Agent Environment</DTXAgentEnvironment>
    <DTXClusterURL>Cluster URL</DTXClusterURL>
    <platform name="android">
        <DTXLogLevel>debug</DTXLogLevel>
    </platform>
    <platform name="ios">
        <DTXLogLevel>ALL</DTXLogLevel>
    </platform>
</NATIVEAGENT>

In this example there are 3 different properties configured for the Mobile Agent. All properties which are available in the Mobile Agent can be used in the <NATIVEAGENT> tag. You can find all the available properties in the documentation of the mobile agent, see the documentation.

The properties DTXAgentEnvironment, DTXClusterURL and DTXApplicationID are defined as global properties (not within platform tag) and will therefore be applied to both platforms (Android and iOS). The property DTXLogLevel is set for the Android and iOS platform differently as their value is not the same. In general, all properties which are defined in a platform tag are overriding a duplicate global value. If for example DTXApplicationID is defined as a global property as well as an Android platform property, always the platform property will have a higher priority.

5. Run auto instrumentation

Execute npm run instrumentDynatrace in the root of your React Native project. This will configure both Android and iOS project with the settings from dynatrace.config.

Command line arguments

This scripts assumes that the usual react native project structure is given. The following arguments can be specified if the project structure is different.

• gradle=C:\MyReactAndroidProject\build.gradle - the location of the root build.gradle file. We will assume that the other gradle file resides in /app/build.gradle. This will add the whole agent dependencies automatically for you and will update the configuration.
• plist=C:\MyReactIOSProject\projectName\info.plist - Tell the script where your info.plist file is. The plist file is used for updating the configuration for the agent.
• config=C:\SpecialFolderForDynatrace\dynatrace.config - If you have not got your config file in the root folder of the React Native project but somewhere else.

6. Build and run your app

Use react-native run-android or react-native run-ios to rebuild and run your app.

Advanced topics

Manual Instrumentation

1. Import and initialize the bridge:

import { Dynatrace } from '@dynatrace/react-native-plugin';

1. Use manual instrumentation almost as you would in a native app. For example:

let myAction = Dynatrace.enterAction("MyButton tapped");
//Perform the action and whatever else is needed.
myAction.leaveAction();

1. You will notice that each method has an addition optional parameter platform of type String. You can use this to only trigger manual instrumentation for a specific OS. The available values are: ios, android and all. If you provide any platform value, then the manual instrumentation call is passed to both iOS and Android. Otherwise it is passed only to the relevant OS. For example:

• Passing to iOS only:

let myAction = Dynatrace.enterAction("MyButton tapped", Dynatrace.PLATFORM_IOS);
//Perform the action and whatever else is needed.
myAction.leaveAction("ios"); 

• Passing to Android only:

let myAction = Dynatrace.enterAction("MyButton tapped", Dynatrace.PLATFORM_ANDROID);
//Perform the action and whatever else is needed.
myAction.leaveAction("android"); 

• Passing to both:

let myAction = Dynatrace.enterAction("MyButton tapped");
//Perform the action and whatever else is needed.
myAction.leaveAction(); 

Please refer to the TypeScript bindings to see the full API that is available for manual instrumentation. The file can be found in the plugin directory ./node_modules/@dynatrace/react-native-plugin/typings/react-native-dynatrace.d.ts.

Debug output

If you like to see the debug output of the Dynatrace React Native plugin you just need to set the global variable DynatraceDebug.

global.DynatraceDebug = true;

Keep in mind the earlier you do this the more output you will get. Recommended position is in the entry point of your application. E.g. index.js

How does Dynatrace determine the user action name?

• React views
  • Dynatrace looks if React views have a display name set (using displayName property).
  • If the display name is not available, the class name will be used.
  • If you minify your react native code you can use the keep_classname setting to preserve the class name.
• Touchables
  • Dynatrace looks for an accessibility label first
  • If the accessibility label is not set, it will take the first inner text that is found in the element hierarchy

Dynatrace documentation

The documentation for OneAgent for Android and iOS is available at the following location:

• Android: https://www.dynatrace.com/support/help/setup-and-configuration/oneagent/android/
• iOS: https://www.dynatrace.com/support/help/setup-and-configuration/oneagent/ios/

Troubleshooting and current restrictions:

Basically if you have problems with the plugin please have a look into the logs. They will tell you what went wrong. The logs can be found in the plugins folder of your React Native project (usually node_modules/@dynatrace/react-native-plugin/logs).

• Currently errors/crashes are reported as errors in the user session and are not visible in the crash overview. This will change in upcoming versions.
• Currently web requests are not linked with user actions. This is because the actions are currently manual and the web request auto-detected. This will change in upcoming versions.
• Missing property DTXApplicationID means that there is no configuration available. Are you sure you called npm run updateConfiguration at least once?
• Be aware if you change your project to pods when you already have installed the plugin, you will end up with duplicate symbols because of the already linked library. Remove the mdoule reference manually from your project.
  
  

---

Changelog

0.172.0

• Error reporting through auto instrumentation
• Debug message output in console

0.171.0

• Added auto instrumentation for React classes

0.168.0

• Initial Beta Release