Prepare release 1.6.1

Improve error handling on beacon send failure

Author: Hongyan Jiang

Changelog.md

@@ -2,6 +2,7 @@
 
 ## 1.6.1
 - Fix crash caused by appendMetaData() inside InstanaProperties class
+- Improve error handling on beacon send failure
 
 ## 1.6.0
 - Refactor code and add more unit test cases

Dev/InstanaAgentExample/AppDelegate.swift

@@ -6,13 +6,19 @@
 
 import UIKit
 import InstanaAgent
+import OSLog
 
 @UIApplicationMain
 class AppDelegate: UIResponder, UIApplicationDelegate {
     var window: UIWindow?   // needed on iOS 12 or lower
 
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-        Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
+        let options = InstanaSetupOptions(enableCrashReporting: true)
+//        options.slowSendInterval = 60.0
+        if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
+            let myLog = OSLog(subsystem: "com.instana.ios.InstanaAgentExample", category: "Instana")
+            os_log("Instana setup failed", log: myLog, type: .error)
+        }
         return true
     }
 

README.md

@@ -59,6 +59,28 @@ func application(_ application: UIApplication, didFinishLaunchingWithOptions lau
 2. The lowest versions that support crash reporting are iOS 14.0 and macOS 12.0.
 3. A valid bundle id other than com.instana.ios.InstanaAgentExample for your test app is also a must.
 
+### How to enable slow send mode on beacon send failure
+
+By default, when beacon send failed, Instana agent tries to resend it until succeed. Beacons are also sent in batches (maximum 100 beacons) every 2 seconds. For certain cellular network, this is not an ideal option.
+An alternative way, slow send mode, is introduced since version 1.6.1. This mode could be turned on by providing a positive slowSendInterval number (in seconds) in setup() call. Then if beacon send failed, Instana agent only sends out one beacon every \(slowSendInterval) seconds. If succeeded, beacon sending restores to normal mode, ie. in batches every 2 seconds. Otherwise sending stays in slow send mode.
+Slow send mode is disabled by default. Here is the example code to set slowSendInterval to 60 seconds:
+
+```
+import InstanaAgent
+
+func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
+    let options = InstanaSetupOptions(options.slowSendInterval: 60.0)
+    if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
+        // Error handling here
+        // Most likely slowSendInterval is invalid. Expected value is 2 ~ 3600 seconds
+    }
+    Instana.setup(key: <Your Instana Key>, reportingURL: <Your Instana instance URL>, options: options)
+
+    ....
+    return true
+}
+```
+
 ### API
 
 See [API page](https://www.ibm.com/docs/en/instana-observability/current?topic=monitoring-ios-api#instana-ios-agent-api).

Sources/InstanaAgent/Beacons/BeaconFlusher.swift

@@ -42,6 +42,7 @@ class BeaconFlusher {
     }
 
     typealias Sender = (URLRequest, @escaping (Swift.Result<Int, Error>) -> Void) -> Void
+    weak var reporter: Reporter?
     let config: InstanaConfiguration
     let debounce: TimeInterval
     let items: Set<CoreBeacon>
@@ -55,16 +56,15 @@ class BeaconFlusher {
     private let externalSend: Sender? // Used for Unit Testing
     private var sentBeacons = Set<CoreBeacon>()
     private(set) var urlTasks = [URLSessionTask]()
-    var shouldPerformRetry: Bool {
-        !errors.isEmpty && retryStep < config.maxRetries
-    }
 
-    init(items: Set<CoreBeacon>,
+    init(reporter: Reporter?,
+         items: Set<CoreBeacon>,
          debounce: TimeInterval,
          config: InstanaConfiguration,
          queue: DispatchQueue,
          send: Sender? = nil,
          completion: @escaping ((BeaconFlusher.Result) -> Void)) {
+        self.reporter = reporter
         self.items = items
         self.config = config
         self.debounce = debounce
@@ -115,7 +115,7 @@ class BeaconFlusher {
         disapatchGroup.notify(queue: queue) { [weak self] in
             guard let self = self else { return }
             self.urlTasks.removeAll()
-            if self.shouldPerformRetry {
+            if self.shouldPerformRetry() {
                 self.retry()
             } else {
                 self.complete()
@@ -124,6 +124,25 @@ class BeaconFlusher {
         didStartFlush?()
     }
 
+    // When error occurred, either goes into slow send mode, or retry sending.
+    internal func shouldPerformRetry() -> Bool {
+        let canDoSlowSend = config.slowSendInterval > 0
+
+        guard !errors.isEmpty else {
+            if canDoSlowSend {
+                // No error, reset the flag
+                reporter?.setSlowSendStartTime(nil)
+            }
+            return false
+        }
+
+        if canDoSlowSend {
+            reporter?.setSlowSendStartTime(Date())
+            return false
+        }
+        return retryStep < config.maxRetries
+    }
+
     private func retry() {
         retryStep += 1
         queue.asyncAfter(deadline: .now() + .milliseconds(retryDelayMilliseconds(for: retryStep)), execute: flush)

Sources/InstanaAgent/Beacons/CoreBeacon/CoreBeacon.swift

@@ -120,6 +120,18 @@ struct CoreBeacon: Codable {
      */
     var m: MetaData?
 
+    mutating func updateMetaDataWithSlowSendStartTime(_ time: Date?) {
+        let key = "slowSendStartTime"
+        if time == nil {
+            m?.removeValue(forKey: key)
+        } else {
+            if m == nil {
+                m = [:]
+            }
+            m![key] = String(time!.millisecondsSince1970)
+        }
+    }
+
     /**
      * User ID
      *

Sources/InstanaAgent/Beacons/Reporter.swift

@@ -11,8 +11,10 @@ public class Reporter {
     var completionHandler = [Completion]()
     let queue: InstanaPersistableQueue<CoreBeacon>
     private let dispatchQueue = DispatchQueue(label: "com.instana.ios.agent.reporter", qos: .utility)
+    private var sendFirstBeacon = true // first beacon is sent all by itself, not in a batch
+    private var slowSendStartTime: Date?
     private var flusher: BeaconFlusher?
-    private let send: BeaconFlusher.Sender?
+    internal var send: BeaconFlusher.Sender?
     private let rateLimiter: ReporterRateLimiter
     private let batterySafeForNetworking: () -> Bool
     private let networkUtility: NetworkUtility
@@ -108,10 +110,27 @@ public class Reporter {
         scheduleFlush()
     }
 
+    internal var isInSlowSendMode: Bool {
+        session.configuration.slowSendInterval > 0 && (sendFirstBeacon || slowSendStartTime != nil)
+    }
+
+    internal func setSlowSendStartTime(_ time: Date?) {
+        if time == nil {
+            if slowSendStartTime != nil {
+                session.logger.add("Slow send ended at \(String(describing: Date()))")
+                slowSendStartTime = nil
+            }
+        } else if slowSendStartTime == nil {
+            // if slow send started, do not update so as to keep the earliest time
+            slowSendStartTime = time
+            session.logger.add("Slow send started at \(String(describing: time!))")
+        }
+    }
+
     func scheduleFlush() {
         guard !queue.items.isEmpty else { return }
         let start = Date()
-        let debounce = queue.isFull ? 0.0 : flushDebounce
+        var debounce: TimeInterval
         let connectionType = networkUtility.connectionType
         guard connectionType != .none else {
             return handle(flushResult: .failure([InstanaError.offline]))
@@ -122,7 +141,24 @@ public class Reporter {
         if suspendReporting.contains(.lowBattery), !batterySafeForNetworking() {
             return handle(flushResult: .failure([InstanaError.lowBattery]))
         }
-        let flusher = BeaconFlusher(items: queue.items, debounce: debounce, config: session.configuration, queue: dispatchQueue, send: send) { [weak self] result in
+        var beacons: Set<CoreBeacon> = Set([])
+        if isInSlowSendMode {
+            if sendFirstBeacon {
+                debounce = flushDebounce
+                sendFirstBeacon = false
+            } else {
+                debounce = session.configuration.slowSendInterval
+            }
+            var beacon = queue.items.first!
+            beacon.updateMetaDataWithSlowSendStartTime(slowSendStartTime)
+            beacons.insert(beacon)
+        } else {
+            debounce = queue.isFull ? 0.0 : flushDebounce
+            beacons = queue.items
+        }
+        let flusher = BeaconFlusher(reporter: self, items: beacons, debounce: debounce,
+                                    config: session.configuration, queue: dispatchQueue,
+                                    send: send) { [weak self] result in
             guard let self = self else { return }
             self.handle(flushResult: result, start)
         }

Sources/InstanaAgent/Configuration/InstanaConfiguraton.swift

@@ -17,6 +17,8 @@ import Foundation
 
 // Use a reference type to avoid a copy when having concurrency
 class InstanaConfiguration {
+    static let maxSlowSendInterval = 3600.0
+
     enum SuspendReporting {
         /// Reporting is suspended while the device battery is low.
         case lowBattery
@@ -46,6 +48,8 @@ class InstanaConfiguration {
     }
 
     struct Defaults {
+        // 0 seconds means disable network probing
+        static let slowSendInterval: Instana.Types.Seconds = 0.0
         static let reporterSendDebounce: Instana.Types.Seconds = 2.0
         static let reporterSendLowBatteryDebounce: Instana.Types.Seconds = 10.0
         static let gzipReport = ProcessInfo.ignoreZIPReporting ? false : true
@@ -62,6 +66,7 @@ class InstanaConfiguration {
     var httpCaptureConfig: HTTPCaptureConfig
     var suspendReporting: Set<SuspendReporting>
     var monitorTypes: Set<MonitorTypes>
+    var slowSendInterval: Instana.Types.Seconds
     var reporterSendDebounce: Instana.Types.Seconds
     var reporterSendLowBatteryDebounce: Instana.Types.Seconds
     var maxRetries: Int
@@ -72,7 +77,8 @@ class InstanaConfiguration {
     var reporterRateLimits: [ReporterRateLimitConfig]
     var isValid: Bool { !key.isEmpty && !reportingURL.absoluteString.isEmpty }
 
-    required init(reportingURL: URL, key: String, httpCaptureConfig: HTTPCaptureConfig, enableCrashReporting: Bool) {
+    required init(reportingURL: URL, key: String, httpCaptureConfig: HTTPCaptureConfig,
+                  enableCrashReporting: Bool, slowSendInterval: Double) {
         self.reportingURL = reportingURL
         self.key = key
         self.httpCaptureConfig = httpCaptureConfig
@@ -81,6 +87,7 @@ class InstanaConfiguration {
         if enableCrashReporting {
             monitorTypes.insert(.crash)
         }
+        self.slowSendInterval = slowSendInterval
         reporterSendDebounce = Defaults.reporterSendDebounce
         reporterSendLowBatteryDebounce = Defaults.reporterSendLowBatteryDebounce
         maxRetries = Defaults.maxRetries
@@ -92,8 +99,8 @@ class InstanaConfiguration {
     }
 
     static func `default`(key: String, reportingURL: URL, httpCaptureConfig: HTTPCaptureConfig = .automatic,
-                          enableCrashReporting: Bool) -> InstanaConfiguration {
+                          enableCrashReporting: Bool, slowSendInterval: Double = 0.0) -> InstanaConfiguration {
         self.init(reportingURL: reportingURL, key: key, httpCaptureConfig: httpCaptureConfig,
-                  enableCrashReporting: enableCrashReporting)
+                  enableCrashReporting: enableCrashReporting, slowSendInterval: slowSendInterval)
     }
 }

Sources/InstanaAgent/Instana.swift

@@ -70,7 +70,46 @@ import Foundation
         }
     }
 
-    /// Configures and sets up the Instana agent with the default configuration.
+    /// Configures and sets up the Instana agent.
+    ///
+    /// - Note: Should be called only once, as soon as posible. Preferably in `application(_:, didFinishLaunchingWithOptions:)`
+    /// - Parameters:
+    ///   - key: Instana key to identify your application.
+    ///   - reportingURL: Reporting URL for the Instana backend.
+    ///   - options: InstanaSetupOptions which includes collectionEnabled, enableCrashReporting,  slowSendInterval etc.
+    ///
+    /// - Returns: true on success, false on error
+    @objc
+    public static func setup(key: String, reportingURL: URL, options: InstanaSetupOptions?) -> Bool {
+        var httpCaptureConfig = HTTPCaptureConfig.automatic
+        var collectionEnabled = true
+        var enableCrashReporting = false
+        var slowSendInterval = 0.0
+        if let options = options {
+            httpCaptureConfig = options.httpCaptureConfig
+            collectionEnabled = options.collectionEnabled
+            enableCrashReporting = options.enableCrashReporting
+
+            let debounce = InstanaConfiguration.Defaults.reporterSendDebounce
+            if options.slowSendInterval != 0.0,
+                options.slowSendInterval < debounce || options.slowSendInterval > InstanaConfiguration.maxSlowSendInterval {
+                // Illegal slowSendInterval. Expected value 2 ~ 3600 in seconds
+                return false
+            }
+            slowSendInterval = options.slowSendInterval
+        }
+        let config = InstanaConfiguration.default(key: key, reportingURL: reportingURL,
+                                                  httpCaptureConfig: httpCaptureConfig,
+                                                  enableCrashReporting: enableCrashReporting,
+                                                  slowSendInterval: slowSendInterval)
+        let session = InstanaSession(configuration: config, propertyHandler: InstanaPropertyHandler(),
+                                     collectionEnabled: collectionEnabled)
+        Instana.current = Instana(session: session)
+        return true
+    }
+
+    /// Deprecated! Use setup( ) with InstanaSetupOptions instead.
+    /// Configures and sets up the Instana agent with the default configuration. (deprecated)
     /// - HTTP sessions will be captured automatically by default
     ///
     /// - Note: Should be called only once, as soon as posible. Preferably in `application(_:, didFinishLaunchingWithOptions:)`
@@ -88,6 +127,7 @@ import Foundation
         Instana.current = Instana(session: session)
     }
 
+    /// Deprecated! Use setup( ) with InstanaSetupOptions instead.
     /// Configures and sets up the Instana agent with a custom HTTP capture configuration.
     ///
     /// - Note: Should be called only once, as soon as posible. Preferably in `application(_:, didFinishLaunchingWithOptions:)`

Sources/InstanaAgent/InstanaSetupOptions.swift

@@ -0,0 +1,30 @@
+//
+//  Copyright © 2023 IBM Corp. All rights reserved.
+//
+
+import Foundation
+
+@objc public class InstanaSetupOptions: NSObject {
+    public var httpCaptureConfig: HTTPCaptureConfig
+    public var collectionEnabled: Bool
+    public var enableCrashReporting: Bool
+    public var slowSendInterval: Instana.Types.Seconds
+
+    /// Instana custom configuration for setup.
+    ///
+    /// - Parameters:
+    ///   - httpCaptureConfig: HTTP monitoring configuration to set the capture behavior (automatic, manual, automaticAndManual or none) HTTP requests & responses
+    ///   - collectionEnabled: Enable or disable collection (instrumentation) on setup. Can be changed later via the property `collectionEnabled` (Default: true)
+    ///   - enableCrashReporting: Subscribe to metricKit events so as to enable crash reporting.
+    ///                           App must have explicitly asked user permission to subscribe before this call.
+    ///   - slowSendInterval: Enable slow send mode on beacon send failure when a positive number is passed
+    @objc public
+    init(httpCaptureConfig: HTTPCaptureConfig = .automatic,
+         collectionEnabled: Bool = true, enableCrashReporting: Bool = false,
+         slowSendInterval: Instana.Types.Seconds = 0.0) {
+        self.httpCaptureConfig = httpCaptureConfig
+        self.collectionEnabled = collectionEnabled
+        self.enableCrashReporting = enableCrashReporting
+        self.slowSendInterval = slowSendInterval
+    }
+}

Sources/InstanaAgent/Utils/Extensions/Double+Misc.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+extension Double {
+    static func == (lhs: Double, rhs: Double) -> Bool {
+        return abs(lhs - rhs) < 0.000001
+    }
+
+    static func != (lhs: Double, rhs: Double) -> Bool {
+        return !(lhs == rhs)
+    }
+}