Auto-instrumentation for iOS 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 provided by your app. It also enables crash detection and performance monitoring related to application startup 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 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 (see below) to your application’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 (and 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 needs to 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, OFF) OneAgent logging will be automatically enabled with this value. If a key isn't present or doesn't have a valid value, automatic logging will be off and you must turn logging on manually in the app. |
DTXApplicationID
|
string
|
This key’s value is used by Dynatrace to identify your mobile app. Auto-instrumentation issues an error if the key isn't present.
|
DTXAgentEnvironment
|
string
|
This key’s value is used to identify Dynatrace environment. Auto-instrumentation issues an error if this key isn't present.
|
DTXClusterURL
|
string
|
The address to your Dynatrace cluster. This value needs to begin with the transport mechanism to be used (http:// or https://).
|
DTXManagedCluster
|
Boolean
|
Must be enabled for Dynatrace Managed only.
|
DTXAgentCertificatePath |
string |
This key 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 |
The default value is true. This setting 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. |
DTXHybridApplication |
BOOL |
The default value is false. Set the value to true if you have a Hybrid application. This is necessary to share the same visit for user actions created by the JavaScript agent. |
DTXSetCookiesForDomain |
String |
For hybrid applications using the JavaScript library, cookies need to be set for each instrumented domain or server the application communicates with. You can specify domains, host or IP addresses. Domains or sub-domains must start with a dot. Separate the list elements with a comma. |
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, Gesture, and ActionSheet. |
DTXExcludedControlClasses |
array |
An array of items where each item contains the name of a UI control (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 |
Set the value to false if you want to disable crash reporting. The default value is true. |
DTXInstrumentLifecycleMonitoring |
Boolean |
Automatic lifecycle detection is enabled without the need to override your view controller classes with the OneAgent for iOS lifecycle classes. Set the value to false to disable automatic lifecycle monitoring. The default value is true. |
DTXInstrumentWebRequestTiming |
Boolean |
The default value is true, which turns on automatic web request timing and tagging. Set the value to false to disable automatic web request timing and tagging. |
DTXInstrumentAutoUserAction |
Boolean |
The default value is true. 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. |
DTXAutoActionTimeoutMilliseconds |
number |
The default value is 500 ms. Sets the value for how long a particular automatic user action is active. The purpose is to catch all web requests that happen 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). |
DTXAutoActionMaxDurationMilliseconds |
number |
The default value is 60000 ms (60 seconds). Sets the amount of time to retain an automatic user action before deletion. The purpose is to catch all web requests that occur when an automatic user action is active. If an automatic user action has pending web requests that are taking a long time 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). |
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 |
The location is captured only if the app uses CLLocationManager and sends the captured location as a metric to the server. OneAgent for iOS doesn't perform GPS location capturing on its own. Set the value to false to disable OneAgent for iOS location capturing. The default value is true. |
DTXUserOptIn |
Boolean |
If set to true, privacy mode is activated and 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 |
If set to false, the agent does not start automatically and needs to be started by either calling startupWithInfoPlistSettings to start with configuration from Info.plist or startupWithConfig to start with 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.
How to use PKH pinning with Dynatrace
Step 1: Generate the hashes from your certificates.
In your Agent kit, you will find the getPKHashFromCertificate.py script. Run this script as follows 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 like Dynatrace.shutdown() or Dynatrace .flushEvents(). You can manually insert these methods and other user-defined actions and events before performing auto-instrumentation.
-
There are two controls that don't yet create auto user actions:
- Gestures
- Certain
UIBarButton items, including custom UIBarButton items added to the navigation bar by storyboard (such as info) that use segues to transition to other views.