Advanced configuration

Latest Dynatrace
Explanation
1-min read
Published Jan 12, 2025

The Dynatrace React Native plugin is configured via the dynatrace.config.js file. This file allows you to define configuration settings for React Native itself and both Android and iOS platforms in a single location. It is typically downloaded from the Dynatrace UI during the initial setup and placed in the root directory of your React Native project.

Configuration file structure

The dynatrace.config.js file in your project root controls the plugin behavior and instrumentation settings. The configuration is structured in three main blocks:

module.exports = {
    react: {
      // Configuration for React Native instrumentation
    },
    android: {
      // Configuration for Android auto instrumentation
    },
    ios: {
      // Configuration for iOS auto instrumentation
    }
}

React configuration

The react block controls React Native-specific instrumentation settings.

Input instrumentation

Configure which files should be instrumented to capture user input:

module.exports = {
  react: {
    input: {
      instrument(filename) {
        return true; // Instrument all files
      },
      actionNamePrivacy: false,
    }
  }
}

Parameters:

instrument(filename)—function called for each file that returns true or false to determine whether to instrument that specific file.
actionNamePrivacy—when true, button and touchable names are hidden (shows "Touch on Button" instead of the actual name). Setting dtActionName on a component overrides this setting.

Use actionNamePrivacy: true to comply with privacy requirements by hiding UI element names.

Lifecycle instrumentation

Configure which files should be instrumented to capture lifecycle changes:

module.exports = {
  react: {
    lifecycle: {
      includeUpdate: false,
      instrument(filename) {
        const path = require('path');
        // Only capture lifecycle in files in src/screens/
        return filename.startsWith(path.join('src', 'screens'));
      }
    }
  }
}

Parameters:

instrument(filename)—function that returns true or false to determine which components to monitor.
includeUpdate—when true, captures component update cycles (can generate many actions).

Be selective with lifecycle instrumentation. Instrumenting all files can generate excessive actions. Focus on actual screen components.

Error handler

Configure crash and error reporting:

module.exports = {
  react: {
    errorHandler: {
      enabled: true,
      reportFatalErrorAsCrash: true,
    }
  }
}

Parameters:

enabled—activates the error/crash handler (default: true).
reportFatalErrorAsCrash—when true, fatal unhandled errors are reported as crashes. When false, they're reported as errors and the session remains open (default: true).

If enabled is false, the reportFatalErrorAsCrash setting is ignored.

Auto start

Enable or disable automatic plugin startup:

module.exports = {
  react: {
    autoStart: true
  }
}

When autoStart is true (default), the plugin starts automatically. Set to false for manual startup via the API.

Debug mode

Enable debug logging:

module.exports = {
  react: {
    debug: true
  }
}

Activates debug mode for more console output during instrumentation and at runtime.

Bundle name

Configure bundle name for multi-bundle setups:

module.exports = {
  react: {
    bundleName: "MyCustomBundle"
  }
}

Use this only when loading multiple .bundle files in your application. The bundle name should be unique to prevent action interference between bundles.

Upstream transformer

Chain multiple transformers:

module.exports = {
  react: {
    upstreamTransformer: require.resolve('react-native-svg-transformer/react-native'),
  }
}

Use this when you have another babel transformer in place alongside the Dynatrace transformer.

Android configuration

The android block contains configuration for Android auto-instrumentation. Copy the content from the Dynatrace web UI mobile application settings:

module.exports = {
  android: {
    config: `
      dynatrace {
        configurations {
          defaultConfig {
            autoStart {
              applicationId "YOUR_APPLICATION_ID"
              beaconUrl "YOUR_BEACON_URL"
            }
          }
        }
      }
    `
  }
}

The content is directly copied to the Gradle file. See the Gradle plugin DSL documentation for all configuration options.

Enable debug logging

android: {
  config: `
    dynatrace {
      configurations {
        defaultConfig {
          autoStart {
            applicationId "YOUR_APPLICATION_ID"
            beaconUrl "YOUR_BEACON_URL"
          }
          debug.agentLogging true
        }
      }
    }
  `
}

User opt-in mode

android: {
  config: `
    dynatrace {
      configurations {
        defaultConfig {
          autoStart {
            applicationId "YOUR_APPLICATION_ID"
            beaconUrl "YOUR_BEACON_URL"
          }
          userOptIn true
        }
      }
    }
  `
}

When enabled, you must query user consent and set privacy settings via the OneAgent SDK.

Build variants

Define different configurations for different build types:

android: {
  config: `
    dynatrace {
      configurations {
        dev {
          variantFilter "Debug"
          autoStart {
            applicationId "DEV_APP_ID"
            beaconUrl "DEV_BEACON_URL"
          }
        }
        prod {
          variantFilter "Release"
          autoStart {
            applicationId "PROD_APP_ID"
            beaconUrl "PROD_BEACON_URL"
          }
        }
      }
    }
  `
}

This allows different application IDs and beacon URLs for different build variants.

iOS configuration

The ios block contains configuration for iOS auto-instrumentation. Copy the content from the Dynatrace web UI mobile application settings:

module.exports = {
  ios: {
    config: `
      <key>DTXApplicationID</key>
      <string>YOUR_APPLICATION_ID</string>
      <key>DTXBeaconURL</key>
      <string>YOUR_BEACON_URL</string>
    `
  }
}

The content is directly copied to the plist file.

Enable debug logging

ios: {
  config: `
    <key>DTXApplicationID</key>
    <string>YOUR_APPLICATION_ID</string>
    <key>DTXBeaconURL</key>
    <string>YOUR_BEACON_URL</string>
    <key>DTXLogLevel</key>
    <string>ALL</string>
  `
}

User opt-in mode

ios: {
  config: `
    <key>DTXApplicationID</key>
    <string>YOUR_APPLICATION_ID</string>
    <key>DTXBeaconURL</key>
    <string>YOUR_BEACON_URL</string>
    <key>DTXUserOptIn</key>
    <true/>
  `
}

Build configurations

Use variables for different build configurations:

ios: {
  config: `
    <key>DTXApplicationID</key>
    <string>\${APPLICATION_ID}</string>
    <key>DTXBeaconURL</key>
    <string>YOUR_BEACON_URL</string>
  `
}

Use \${} syntax (with backslash) to define variables. Set these variables using Xcode build configuration pre-build scripts.

Manual startup configuration

For manual startup, disable auto start and configure startup parameters via the API:

module.exports = {
  react: {
    autoStart: false,
  },
  android: {
    config: `
      dynatrace {
        configurations {
          defaultConfig {
            autoStart.enabled false
          }
        }
      }
    `
  },
  ios: {
    config: `
      <key>DTXAutoStart</key>
      <false/>
    `
  }
}

Then start the plugin in your application code:

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

const config = new ConfigurationBuilder("beaconUrl", "applicationId")
  .withCrashReporting(true)
  .withLogLevel(LogLevel.Info)
  .buildConfiguration();

await Dynatrace.start(config);

Manual startup options

The ConfigurationBuilder provides the following configuration methods:

Method	Type	Default	Description
`withCrashReporting(value)`	boolean	true	Enable crash reporting
`withErrorHandler(value)`	boolean	true	Enable error/crash handler
`withReportFatalErrorAsCrash(value)`	boolean	true	Report fatal errors as crashes
`withLogLevel(level)`	LogLevel	LogLevel.Info	Set log level (Info or Debug)
`withLifecycleUpdate(value)`	boolean	false	Include component update cycles in lifecycle actions
`withUserOptIn(value)`	boolean	false	Enable user opt-in mode
`withActionNamePrivacy(value)`	boolean	false	Hide button and touchable names
`withBundleName(name)`	string	undefined	Set bundle name for multi-bundle setups

Manual startup configuration values override the base configuration from dynatrace.config.js. For example, if lifecycleUpdate is enabled in the config file, you can still disable it via withLifecycleUpdate(false).

Apply configuration changes

After modifying dynatrace.config.js, apply the changes:

npx instrumentDynatrace

Then reset the metro cache:

react-native start --reset-cache

Configuration changes require both running npx instrumentDynatrace and resetting the metro cache to take effect.

React Native 0.70 or newer

The automated configuration script no longer runs automatically. Always execute npx instrumentDynatrace manually after configuration changes.