iOS auto instrumentation

Auto-Instrumentation for iOS instruments iOS applications to be monitored using the Mobile Agent. The instrumentation process is an automated way to add the Mobile Agent to an application without manually modifying the source code. The auto-instrumented application is equivalent to an application manually instrumented for basic data collection. This level of instrumentation provides visibility into real user experiences of the flow within the application, crash detection, and performance monitoring of application startup and web request response times.

Auto-Instrumentation Features

The following features are automatically instrumented:

  • Automatic Mobile Agent startup ‐ You must use instrumentation keys to configure the automatic startup.
  • Lifecycle data
  • Crash reporting
  • Web request tagging
  • Web request events (reporting execution time and identifying 3rd party requests)
  • Web views
  • Automatic user action detection (the detection and timing of certain user actions such as button presses and other view actions and controls)

All these functions are enabled by default. You can disable or refine the Auto-Instrumentation functions by adding configuration keys to your application’s Info.plist file.

You can combine manual instrumentation with Auto-Instrumentation. For example, you may want to manually instrument certain user-defined actions (and report values and events) at development time, and then use Auto-Instrumentation to add the previously listed features to your application.

Auto-Instrumentation Overview

  1. Link the iOS Mobile Mobile Agent static library or framework to your application and build it in Xcode. See iOS Agent manual setup for details.
  2. Add keys to your application's Info.plist file to configure the automatic instrumentation.
  3. Auto-instrumentation happens during runtime. The resulting application is instrumented to the levels configured in the application's Info.plist file.

Instrumentation keys

The keys (properties) in the following table are the configuration options for automatic instrumentation. Add the keys to your application's Info.plist file as needed to fine-tune the Auto-Instrumentation.

If you want to keep your Info.plist file clean you can move all mobile agent 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.

Many of the properties reflect the method parameters of the instrumentation API. You can find them in the iOS manual instrumentation topic.

Key Key Type Description
DTXLogLevel String If this key is present with a valid value (ALL, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, OFF) Mobile Agent logging is automatically enabled with this value. If the key is not present or does not have a valid value, automatic logging is off and you must turn logging on manually in the app.
DTXAgentStartupPath String If this key is present with a valid value, the Mobile Agent starts automatically and using this value as the serverUrl name. It ignores any manual startupWithApplicationName calls in your app. serverUrl must start with the transport mechanism to use (http:// or https://). If it is not present, you must make a manual call to startupWithApplicationName to start the Mobile Agent.
DTXMonitorCookie String If this key is present, the value is automatically added as a cookie for HTTP requests to the serverUrl (see DTXAgentStartupPath in this table) so that they can pass your infrastructure's requirements.
DTXApplicationID String his key's value is used as your application ID to identify it on the AppMon Server. An error is generated if it is not present.
DTXAllowAnyCert BOOL Equivalent to the allowAnyCert parameter in the startup call. If set to true, all certificates are accepted. If set to false, valid certificates from known certificate authorities are accepted. The default value is false.
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 BOOL Detects and times web requests originating from web views in your hybrid app. Set the value to false to disable automatic detection and timing of web view web requests. The default value is true.
DTXExcludedControls Array This key 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. The possible values are Button, DatePicker, Slider, Stepper, Switch, RefreshControl, ToolBar, SegmentedControl, TableView, TabBar, AlertView, AlertAction, PageView, NavigationController, CollectionView, Gesture and ActionSheet.
DTXExcludedLifecycleClasses Array This is 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 BOOL Set to false if you do not want crash reporting. If you want to report crashes to a server other than the AppMon Server or to enable sending email notification of crashes, add the appropriate enableCrashReportingWithReport API call in your code to override the default. The default value is true.
DTXSendCrashReports BOOL Corresponds to the sendCrashReport parameter for enableCrashReportingwithReport to send crash reports to the AppMon Server. Set the key to false if you do not want to send crash reports. The default value is true.
DTXInstrumentLifecycleMonitoring BOOL Automatic lifecycle detection is enabled without the need to override your view controller classes with the iOS Mobile Agent lifecycle classes. Set the value to false to disable automatic lifecycle monitoring. The default value is true.
DTXInstrumentWebRequestTagging BOOL Set to true (default), which turns on automatic web request tagging. webRequestTagging is enabled if webRequestTiming is enabled, because it is a dependency. You must set both webRequestTiming and webRequestTagging to false to turn off automatic web request tagging.
DTXInstrumentWebRequestTiming BOOL The default value is true, which turns on automatic web request timing. Set the value to false to disable automatic web request timing. Note that webRequestTagging is enabled if webRequestTiming is enabled, because it is a dependency.
DTXInstrumentWebRequestActionWrapping BOOL The default value is true. It automatically wraps web requests in user actions if a manual user action or automatic user action is not available. Set the value to false to disable automatic wrapping of web request actions.
DTXInstrumentAutoUserAction BOOL The default value is true. It turns on the ability to automatically create user actions for user interactions with the app, such as button presses. Set the value to false to disable automatic creation of user actions.
DTXAutoActionTimeoutMilliseconds Number The default value is 500 ms. It 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, the Mobile Agent 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). It sets the value to retain an automatic user action before deletion. The purpose is to catch all web requests that happen when an automatic user action is active. If the automatic user action has pending web requests that are taking a long time to complete, the Mobile Agent 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 BOOL Determines whether to send automatic user actions that don't contain any web requests or lifecycle actions. The default value is false.
DTXInstrumentGPSLocation BOOL The location is captured only if the app uses CLLocationManager and sends the captured location as a metric to the server. The iOS agent does no GPS location capturing on its own. Set to false to disable iOS agent location capturing. The default value is true.

Limitations

  • An auto-instrumented application cannot 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 do not 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 another view.