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"

Advanced configuration example

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

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:

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.

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

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.

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:

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,
    ),
  );
}

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.

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.