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 This 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 (relative to the main bundle 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.
DTXAuthenticationClassDelegate String This key defines the name of the custom AuthenticationManager class to be used by the agent communication in case Advanced authentication is used.
AppMon 2018 April and later DTXUserOptIn BOOL If set to true, the privacy mode is activated and user consent needs to be set according to Data privacy section.
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. This should not be used together with DTXHybridApplication as in this scenario the web request should be tracked by the JavaScript Agent
AppMon 2018 April and later 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.
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.
DTXInstrumentWebRequestTiming BOOL 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.
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 Mobile Agent doesn't capture GPS location on its own.

Set to false to disable location capture. The default value is true.
DTXPublicKeyPins Array AppMon 2018 October and later This is an array of dictionaries, each carrying the following keys and values. For usage, please see Security and Authentication.
Key 1: DTXPKHash
  • Type: String
  • Value: public key hash.
Key 2: DTXPKHashAlgoritm
  • Type: String
  • Value: The hash algorithm used. Possible values are below.
Possible Hash Algorithm values:
  • DTXAlgorithmRsa2048
  • DTXAlgorithmRsa4096
  • DTXAlgorithmEcDsaSecp256r1
  • DTXAlgorithmEcDsaSecp384r1

Security and authentication

In AppMon 2018 October 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 AppMon

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 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.