Configuration

Latest Dynatrace
How-to guide
Published Dec 24, 2025

The Dynatrace OneAgent for iOS is configured primarily through your app's Info.plist file. This approach allows you to define configuration settings at build time. For scenarios requiring runtime configuration, you can use manual startup instead.

To keep your app's Info.plist file clean, you can move all OneAgent-related DTX keys to a separate Dynatrace.plist file. Create this file in the same location as your Info.plist and add it to your target's Copy Bundle Resources build phase. The Dynatrace.plist file must be located at the root of your resources bundle. For more information, see Info.plist file.

For a complete list of all available configuration keys, see iOS configuration keys.

Configuration keys

The following tables list the most commonly used configuration keys for the iOS OneAgent. Add these keys to your app's Info.plist file to customize OneAgent behavior.

Required configuration

Configuration key	Type	Description
`DTXApplicationID`	String	Your application's unique identifier. Get this from the Dynatrace instrumentation wizard.
`DTXBeaconURL`	String	The beacon endpoint URL for your Dynatrace environment. Get this from the Dynatrace instrumentation wizard.

General configuration

Configuration key	Type	Default	Description
`DTXAutoStart`	Boolean	`true`	When `true`, OneAgent starts automatically when your app launches. Set to `false` for manual startup.
`DTXUserOptIn`	Boolean	`false`	When `true`, OneAgent doesn't capture any data until the user explicitly opts in via `Dynatrace.applyUserPrivacyOptions(...)`.
`DTXLogLevel`	String	`OFF`	Controls the verbosity of OneAgent logging. Values: `ALL`, `INFO`, `WARNING`, `SEVERE`, `OFF`.

Crash and ANR reporting

Configuration key	Type	Default	Description
`DTXCrashReportingEnabled`	Boolean	`true`	Enables or disables automatic crash reporting.
`DTXANRReportingEnabled`	Boolean	`true`	Enables or disables Application Not Responding (ANR) detection.

Web request instrumentation

Configuration key	Type	Default	Description
`DTXInstrumentWebRequestTiming`	Boolean	`true`	Enables or disables automatic web request instrumentation.
`DTXURLFilters`	Array	`[]`	An array of URL patterns to exclude from automatic instrumentation. Supports wildcards.

View and lifecycle instrumentation

Configuration key	Type	Default	Description
`DTXInstrumentLifecycleMonitoring`	Boolean	`true`	Enables or disables automatic view lifecycle monitoring for `UIViewController` subclasses.
`DTXExcludedLifecycleClasses`	Array	`[]`	An array of `UIViewController` class names to exclude from lifecycle monitoring.

For additional configuration options including user action instrumentation, hybrid application settings, location tracking, and certificate pinning, see iOS configuration keys.

Configuration example

The following example shows a typical Info.plist configuration:

Example Info.plist configuration

<key>DTXApplicationID</key>
<string>YOUR_APPLICATION_ID</string>
<key>DTXBeaconURL</key>
<string>https://your-environment.dynatrace.com/mbeacon</string>
<key>DTXLogLevel</key>
<string>OFF</string>
<key>DTXCrashReportingEnabled</key>
<true/>
<key>DTXInstrumentWebRequestTiming</key>
<true/>
<key>DTXUserOptIn</key>
<false/>

Manual startup

By default, OneAgent starts automatically when your app launches. If you need to configure values like beaconUrl or applicationId at runtime, you can use manual startup instead.

Automatic startup captures early lifecycle events, such as the application start. Manual startup occurs later, meaning those early events aren't captured until the agent is initialized.

Disable automatic startup

First, disable automatic startup in your Info.plist:

<key>DTXAutoStart</key>
<false/>

Start OneAgent manually

Call Dynatrace.startupWithConfig(...) as early as possible in your app's lifecycle—ideally in application(_:didFinishLaunchingWithOptions:).

import Dynatrace

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Dynatrace.startupWithConfig([
            kDTXApplicationID: "YOUR_APPLICATION_ID",
            kDTXBeaconURL: "https://your-environment.dynatrace.com/mbeacon"
        ])
        return true
    }
}

Startup with additional options

You can pass additional configuration options during manual startup using the same keys as in Info.plist:

Dynatrace.startupWithConfig([
    kDTXApplicationID: "YOUR_APPLICATION_ID",
    kDTXBeaconURL: "https://your-environment.dynatrace.com/mbeacon",
    kDTXCrashReportingEnabled: true,
    kDTXLogLevel: "INFO",
    kDTXAllowAnyCert: false,
    kDTXUserOptIn: false
])

Values passed to Dynatrace.startupWithConfig(...) take precedence over Info.plist settings. Any settings not included in the dictionary fall back to Info.plist values or defaults. Make sure to disable auto-start if you plan on starting the agent manually.

Debug logging

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

Debug logging is intended for development and troubleshooting purposes only. Don't enable it in production environments.

Enable debug logging

To enable debug logging for iOS, add the DTXLogLevel configuration key to your app's Info.plist file:

<key>DTXLogLevel</key>
<string>ALL</string>

Alternatively, enable logging programmatically during manual startup:

Dynatrace.startupWithConfig([
    kDTXApplicationID: "YOUR_APPLICATION_ID",
    kDTXBeaconURL: "https://your-environment.dynatrace.com/mbeacon",
    kDTXLogLevel: "ALL"
])