Advanced configuration

Latest Dynatrace
How-to guide
1-min read
Published Dec 24, 2025

The Dynatrace Flutter plugin is configured via the dynatrace.config.yaml file. This file allows you to define configuration settings for 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 Flutter project.

Configuration file structure

The dynatrace.config.yaml file consists of two main sections: android and ios. Each section contains a config block where you define the platform-specific settings.

android:
  config: "ANDROID_CONFIGURATION"

ios:
  config: "IOS_CONFIGURATION"

android—contains configuration for the Android OneAgent using the Gradle DSL syntax.
ios—contains configuration for the iOS OneAgent using the Info.plist XML format.

Advanced configuration example

Below is an example of a dynatrace.config.yaml file showing commonly used configuration options for both platforms.

Advanced configuration example

android:
  config:
    "dynatrace {
      configurations {
        defaultConfig {
          autoStart {
            applicationId 'YOUR_ANDROID_APP_ID'
            beaconUrl 'https://your-environment.dynatrace.com/mbeacon'
          }
          userOptIn false
          crashReporting true
          debug.agentLogging true
          debug.certificateValidation true
          webRequests.enabled true
          agentBehavior.startupLoadBalancing true
          agentBehavior.startupWithGrailEnabled true
        }
      }
    }"

ios:
  config:
    "<key>DTXApplicationID</key>
    <string>YOUR_IOS_APP_ID</string>
    <key>DTXBeaconURL</key>
    <string>https://your-environment.dynatrace.com/mbeacon</string>
    <key>DTXUserOptIn</key>
    <false/>
    <key>DTXCrashReportingEnabled</key>
    <true/>
    <key>DTXLogLevel</key>
    <string>ALL</string>
    <key>DTXAllowAnyCert</key>
    <true/>
    <key>DTXInstrumentWebRequestTiming</key>
    <true/>
    <key>DTXStartupLoadBalancing</key>
    <true/>
    <key>DTXStartupWithGrailEnabled</key>
    <true/>"

For a complete list of available configuration options, refer to the platform-specific documentation:

Common configuration options

The following table lists common configuration options and their equivalents on Android and iOS:

Configuration	Default	Android	iOS	Description
Application ID	Required	`autoStart.applicationId`	`DTXApplicationID`	Identifies your mobile app in Dynatrace
Beacon URL	Required	`autoStart.beaconUrl`	`DTXBeaconURL`	Identifies your Dynatrace environment
User Opt-In	false	`userOptIn`	`DTXUserOptIn`	Enables privacy mode requiring user consent
Crash Reporting	true	`crashReporting`	`DTXCrashReportingEnabled`	Enables automatic crash reporting
Debug Logging	false	`debug.agentLogging`	`DTXLogLevel`	Enables detailed agent logging to the mobile devices OSLog/Logcat
Certificate Validation	true	`debug.certificateValidation`	`DTXAllowAnyCert`	Controls self-signed certificate acceptance
Web Request Tracking	true	`webRequests.enabled`	`DTXInstrumentWebRequestTiming`	Enables automatic web request monitoring

Apply configuration changes

Modifying the dynatrace.config.yaml file does not automatically update your native Android and iOS projects. You must apply the changes manually by running the configuration script.

Make your changes to dynatrace.config.yaml.
Run the following command in the root of your Flutter project:
```
dart run dynatrace_flutter_plugin
```

This command parses the YAML file and updates the build.gradle (Android) and Info.plist (iOS) files with the new configuration.

You must re-run dart run dynatrace_flutter_plugin every time you modify dynatrace.config.yaml.

Custom paths

If your project structure differs from the standard Flutter layout, you can specify custom paths for the configuration file or native project files:

# Custom config file location
dart run dynatrace_flutter_plugin --config="/path/to/dynatrace.config.yaml"

# Custom Android Gradle file
dart run dynatrace_flutter_plugin --gradle="/custom/path/to/build.gradle"

# Custom iOS plist file
dart run dynatrace_flutter_plugin --plist="/custom/path/to/Info.plist"

Perform manual startup

By default, the Dynatrace OneAgent starts automatically using the configuration from dynatrace.config.yaml. If you need to configure values like beaconUrl or applicationId at runtime, you can use manual startup instead.

Automated startup captures early lifecycle events, such as the application start. Manual startup occurs later, meaning those early events will be missed until the agent is initialized.

Deactivate automatic startup

First, disable automatic startup in your dynatrace.config.yaml:

android:
  config:
    "dynatrace {
      configurations {
        defaultConfig {
          autoStart.enabled false
        }
      }
    }"
ios:
  config:
    "<key>DTXAutoStart</key>
    <false/>"

Run dart run dynatrace_flutter_plugin to apply the changes.

Start the agent manually

Pass a Configuration object to the start() method with at least beaconUrl and applicationId:

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';

void main() {
  Dynatrace().start(
    MyApp(),
    configuration: Configuration(
      beaconUrl: 'https://your-environment.dynatrace.com/mbeacon',
      applicationId: 'your-application-id',
    ),
  );
}

Configuration options

The Configuration object supports the following options:

Property	Type	Default	Description
`beaconUrl`	String	Required	Identifies your Dynatrace environment
`applicationId`	String	Required	Identifies your mobile app
`reportCrash`	bool	true	Enables automatic crash reporting
`logLevel`	LogLevel	LogLevel.Info	Set to `LogLevel.Debug` for verbose logging
`certificateValidation`	bool	true	Set to `false` to accept self-signed certificates
`userOptIn`	bool	false	Enables privacy mode requiring user consent

Example with all options

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';

void main() {
  Dynatrace().start(
    MyApp(),
    configuration: Configuration(
      beaconUrl: 'https://your-environment.dynatrace.com/mbeacon',
      applicationId: 'your-application-id',
      reportCrash: true,
      logLevel: LogLevel.Debug,
      certificateValidation: true,
      userOptIn: false,
    ),
  );
}

Any values not explicitly set in the Configuration object will fall back to those defined in dynatrace.config.yaml, or to default values if not present there.

Debug logging

Enable debug logging to troubleshoot issues with data collection or agent initialization. This provides detailed output from the OneAgent in your device logs.

Debug logging is intended for development and troubleshooting purposes only and should not be enabled in production environments.

Activate debug logging

To enable debug logging, update your dynatrace.config.yaml:

Android: set debug.agentLogging to true.

android:
  config:
    "dynatrace {
      configurations {
        defaultConfig {
          // ... other config
          debug.agentLogging true
        }
      }
    }"

iOS: set DTXLogLevel to ALL.

ios:
  config:
    "
    <!-- ... other config -->
    <key>DTXLogLevel</key>
    <string>ALL</string>
    "

After updating the file, remember to run dart run dynatrace_flutter_plugin to apply the changes.