Configuration settings

The auto-instrumentation process instruments your iOS apps for monitoring with OneAgent. The instrumentation process is an automated way of adding OneAgent to an app without manually modifying its source code. An auto-instrumented app is equivalent to an app that is manually instrumented for basic data collection. This level of instrumentation provides visibility into the real user experience delivered by your app. It also enables crash detection and performance monitoring related to app start-up and web request response times.

Auto-instrumentation features

The following features are automatically instrumented:

Automatic OneAgent startup
Lifecycle data
Crash reporting
Web request tagging
Web request events execution time and the data sent are reported, 3rd-party requests are identified
Web views
Automatic user action detection (detection and timing of user actions, such as button clicks, view actions, and other controls)

All these features are enabled by default. You can disable or refine auto-instrumentation functions by adding configuration keys to your app’s Info.plist file.

Auto-instrumentation occurs during runtime. The resulting app is instrumented to the levels configured in the app's Info.plist file.

You can combine manual instrumentation with auto-instrumentation to capture additional details. For example, you may want to manually instrument certain user-defined actions, report values, and events.

Configuration keys

Configuration keys are essentially properties you can set to your preferences for auto-instrumentation. Add the keys to your app's Info.plist file, as required to fine-tune auto-instrumentation.

To keep your Info.plist file clean, move all OneAgent-related DTX keys to a Dynatrace.plist file and add the Dynatrace.plist to the Copy Bundle Resources build phase. The Dynatrace.plist file must be at the root of your resources bundle, so it should be created in the same location as the Info.plist file.

The following table includes all configuration keys for iOS auto-instrumentation.

Configuration keys

Key	Key Type	Description
`DTXLogLevel`	string	If this key is present with a valid value (`ALL`, `FINEST`, `FINER`, `FINE`, `CONFIG`, `INFO`, `WARNING`, `SEVERE`, or `OFF`), automatically enables OneAgent logging with the set value. If a key isn't present or doesn't have a valid value, automatic logging is switched off and must be switched on manually in the app.
`DTXApplicationID`	string	Identifies your mobile app. Auto-instrumentation issues an error if the key isn't present.
`DTXBeaconURL`	String	This key’s value is used to identify your environment within Dynatrace. Auto-instrumentation issues an error if the key is not present.
~~`DTXAgentEnvironment`~~	string	Identifies the Dynatrace environment. Auto-instrumentation issues an error if this key isn't present. Note: This key is obsolete as of 8.x and replaced by `DTXBeaconURL`.
~~`DTXClusterURL`~~	string	The address of your Dynatrace cluster. This value must begin with the transport mechanism to be used: `http://` or `https://`. Note: This key is obsolete as of 8.x and replaced by `DTXBeaconURL`.
~~`DTXManagedCluster`~~	boolean	Must be enabled for Dynatrace Managed only. Note: This key is obsolete as of 8.x and replaced by `DTXBeaconURL`.
`DTXStartupLoadBalancing`	boolean	Enables agent-side load balancing on startup. By default, this is set to `false`. When set to `true`, this enables agent-side load balancing, which avoids unbalanced load on the server when multiple OneAgents simultaneously establish a connection to the ActiveGate. If OneAgent is used as a beacon endpoint in place of an ActiveGate, this configuration key requires OneAgent version 1.195+. Note: This key is available as of OneAgent for iOS 8.203.
`DTXAllowAnyCert`	boolean	Allows the use of self-signed certificates. By default, it is set to `false`. When set to `true`, OneAgent for iOS accepts self-signed certificates (certificates that are not signed by a `root-CA`). This configuration key doesn't impact mobile app connections. It's only used for OneAgent communication, but doesn't overrule the host-name validation.
`DTXAgentCertificatePath`	string	Defines the path to a (self-signed) certificate in `DER` format, which is used as an additional anchor to validate HTTPS communication. This key is needed if `DTXAllowAnyCert` is `false` and a self-signed certificate is used on the server. The default value is `null`.
`DTXInstrumentWebViewTiming`	boolean	Turns on automatic web request timing and tagging for requests passed to a WebView. This doesn't work for requests issued from JavaScript inside a WebView. Set the value to `false` to disable automatic web request timing and tagging. The default value is `true`.
`DTXFilterURLProtocolDuplicates`	boolean	Required if NSURLProtocol subclassing is used and duplicate web requests may appear. The default value is `false`. Note: This key is available as of OneAgent for iOS 8.172 and 7.2.6.
`DTXHybridApplication`	boolean	For hybrid apps, set the value to `true`. This is necessary to share the same visit for user actions created by the RUM JavaScript tag. The default value is `false`.
`DTXSetCookiesForDomain`	array[string]	For hybrid apps that use the JavaScript library, cookies must be set for each instrumented domain or server that the app communicates with. You can specify domains, host, or IP addresses. Domains and sub-domains must start with a dot.
`DTXWebViewStandInDelegate`	boolean	Use different instrumentation mode for WebView delegates to prevent circular instrumentation on delegate switching involving a subclass. The default value is `false`. Note: This key is available as of OneAgent for iOS 8.175 and 7.2.7.
`DTXExcludedControls`	array	Defines an array of items where each item contains a type of view or control to exclude from automatic creation of user actions. Each item in the array is a case-insensitive string. Possible values are `Button`, `DatePicker`, `Slider`, `Stepper`, `Switch`, `RefreshControl`, `ToolBar`, `SegmentedControl`, `TableView`, `TabBar`, `AlertView`, `AlertAction`, `PageView`, `NavigationController`, `CollectionView`, and `ActionSheet`.
`DTXExcludedControlClasses`	array	An array of items where each item contains the name of a UI control class (or sub-class) to exclude from automatic control instrumentation. Each item in the array is a case-sensitive string that must exactly match the name of the class to be excluded.
`DTXExcludedLifecycleClasses`	array	An array of items where each item contains the name of a class to exclude from automatic lifecycle instrumentation. Each item in the array is a case-sensitive string that must exactly match the name of the class to be excluded.
`DTXCrashReportingEnabled`	boolean	Enables crash reporting. To disable crash reporting, set the value to `false`. The default value is `true`.
`DTXInstrumentLifecycleMonitoring`	boolean	Enables automatic lifecycle detection without the need to override your view controller classes with the OneAgent SDK for iOS lifecycle classes. To disable automatic lifecycle monitoring, set the value to `false`. The default value is `true`.
`DTXInstrumentWebRequestTiming`	boolean	Turns on automatic web request timing and tagging. To disable automatic web request timing and tagging, set the value to `false`. The default value is `true`.
`DTXInstrumentAutoUserAction`	boolean	Turns on the ability to automatically create user actions for user interactions with the app, such as button clicks. Set the value to `false` to disable automatic creation of user actions. The default value is `true`.
`DTXInstrumentFrameworks`	boolean	Enables automatic lifecycle instrumentation for 3rd party frameworks that are bundled with the app. Set the value to `true` to enable automatic 3rd party framework lifecycle instrumentation. The default value is `false`.
`DTXAutoActionTimeoutMilliseconds`	number	Sets the value for how long a particular automatic user action is active. The purpose is to detect all web requests that occur when an automatic user action is active. If the automatic user action has completed web requests, OneAgent leaves the action at the end of this time. The minimum allowed value is `100 ms`, the maximum allowed value is `5000 ms` (five seconds). The default value is `500 ms`.
`DTXAutoActionMaxDurationMilliseconds`	number	Sets the amount of time to retain an automatic user action before deletion. The purpose is to detect all web requests that occur when an automatic user action is active. If an automatic user action has pending web requests that are taking longer to complete, OneAgent waits for this amount of time for the web requests to complete before leaving the user action. The minimum allowed value is `100 ms`, the maximum allowed value is `540000 ms` (nine minutes). The default value is `60000 ms` (60 seconds).
`DTXSendEmptyAutoAction`	boolean	Determines whether to send automatic user actions that don't contain any web requests or lifecycle actions. The default value is `true`.
`DTXInstrumentGPSLocation`	boolean	Captures the location only if the app uses `CLLocationManager` and sends the captured location as a metric to the server. The OneAgent SDK for iOS doesn't perform GPS location capturing on its own; it only captures three fractional digits to protect the privacy of the end user. Set the value to `false` to disable location capturing. The default value is `true`.
`DTXUserOptIn`	boolean	When set to `true`, activates the privacy mode. The user consent needs to be queried and set. The privacy settings for data collection and crash reporting can be changed via the OneAgent SDK for Mobile like described in Data privacy. The default value is `false`.
`DTXAutoStart`	boolean	When set to `false`, the agent does not start automatically and must be started by either calling `startupWithInfoPlistSettings` to start with the configuration from `Info.plist` or `startupWithConfig` to start with the passed configuration dictionary. Configuration keys for the dictionary are the same as listed in this table. They can also be found in the `Dynatrace.h` header file shipped with the agent. The default value is `true`.

Security and authentication

You can use the Public Key Hash Pinning feature for authentication purposes.

Caution

Public key pinning can be dangerous. If you make a mistake, you might cause your app to pin a set of keys that validates today but which stops validating a week or a year from now. In that case, your app will no longer be able to connect to the server and will most likely stop working until it gets updated with a new set of keys.

How to use PKH pinning with Dynatrace

Step 1

Generate the hashes from your certificates. From your agent kit run the getPKHashFromCertificate.py script to generate a hash from your certificate:

python getPKHashFromCertificate.py <path to your cert>.<der|pem> --type <DER | PEM>

The output should look like this:

CERTIFICATE INFO
----------------
subject= *****
issuer= *****
SHA1 Fingerprint= ******

---------------------- DTXDomainPins item ----------------------
DTXPKHash: SomePublicKeyHash=
DTXPKHashAlgoritm: DTXAlgorithmRsa2048

Step 2

Use the output from the script in your info.plist as a dictionary under the key DTXPublicKeyPins as explained above.

Limitations

An auto-instrumented application can't carry out functions such as Dynatrace.shutdown() or Dynatrace .flushEvents(). You can manually insert these methods and other user-defined actions and events before performing auto-instrumentation.
The following controls can't be used to create auto user actions:
- Gestures
- Certain UIBarButton items, including custom UIBarButton items added to the navigation bar by a storyboard (such as info) that use segues to transition to other views.