add drop beacon handler

Author: Hongyan Jiang

Changelog.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.8.4
+- add drop beacon handler
+
 ## 1.8.3
 - update minimum supported iOS version to 12 (was 11 before)
 - do not rate limit session start beacon and crash beacons

InstanaAgent.podspec

@@ -16,7 +16,7 @@ Pod::Spec.new do |s|
   #
 
   s.name         = "InstanaAgent"
-  s.version      = "1.8.3"
+  s.version      = "1.8.4"
   s.summary      = "Instana iOS agent."
 
   # This description is used to generate tags and improve search results.

Sources/InstanaAgent/Beacons/Beacons Types/Beacon.swift

@@ -16,6 +16,10 @@ class Beacon: Identifiable {
         self.viewName = ViewChange.validate(viewName: viewName)
     }
 
+    func extractDropBeaconValues() -> DropBeacon? {
+        return nil
+    }
+
     // A hex encoded 64 bit random ID.
     static func generateUniqueIdImpl() -> String {
         let validIdCharacters = Array("0123456789abcdef")

Sources/InstanaAgent/Beacons/Beacons Types/CustomBeacon.swift

@@ -16,6 +16,7 @@ class CustomBeacon: Beacon {
     let error: Error?
     let metaData: MetaData?
     let customMetric: Double?
+    let eventType: String? // internal meta
 
     init(timestamp: Instana.Types.Milliseconds? = nil,
          name: String,
@@ -24,7 +25,8 @@ class CustomBeacon: Beacon {
          error: Error? = nil,
          metaData: MetaData? = nil,
          viewName: String? = CustomBeaconDefaultViewNameID,
-         customMetric: Double? = nil) {
+         customMetric: Double? = nil,
+         eventType: String? = nil) {
         self.duration = duration
         self.name = name
         self.error = error
@@ -38,6 +40,14 @@ class CustomBeacon: Beacon {
             start = timestamp
         }
         self.customMetric = customMetric
+        self.eventType = eventType
         super.init(timestamp: start, viewName: viewName)
     }
+
+    override func extractDropBeaconValues() -> CustomEventDropBeacon {
+        return CustomEventDropBeacon(timestamp: timestamp, eventName: name, view: viewName,
+                                     errorCount: (error != nil) ? 1 : nil,
+                                     errorMessage: (error != nil) ? "\(error!.localizedDescription)" : nil,
+                                     customMetric: (customMetric != nil) ? "\(customMetric!)" : nil)
+    }
 }

Sources/InstanaAgent/Beacons/Beacons Types/HTTPBeacon.swift

@@ -40,4 +40,10 @@ class HTTPBeacon: Beacon {
         self.backendTracingID = backendTracingID
         super.init(timestamp: timestamp, viewName: viewName)
     }
+
+    override func extractDropBeaconValues() -> HTTPDropBeacon {
+        return HTTPDropBeacon(timestamp: timestamp, url: url.absoluteString,
+                              hsStatusCode: String(responseCode),
+                              view: viewName, hmMethod: method, headers: header)
+    }
 }

Sources/InstanaAgent/Beacons/Beacons Types/ViewChange.swift

@@ -51,6 +51,10 @@ class ViewChange: Beacon {
         return true
     }
 
+    override func extractDropBeaconValues() -> ViewDropBeacon {
+        return ViewDropBeacon(timestamp: timestamp, viewName: viewName, imMap: viewInternalCPMetaMap)
+    }
+
     static func validate(viewName: String?) -> String? {
         guard let value = viewName else { return nil }
         return value.cleanEscapeAndTruncate(at: InstanaProperties.viewMaxLength)

Sources/InstanaAgent/Beacons/CoreBeacon/CoreBeaconFactory.swift

@@ -197,6 +197,10 @@ extension CoreBeacon {
         if let customMetric = beacon.customMetric {
             cm = String(customMetric)
         }
+        if let eventType = beacon.eventType {
+            im = MetaData()
+            im![internalMetaDataKeyCustom_eventType] = eventType
+        }
     }
 
     private mutating func add(error: Error) {

Sources/InstanaAgent/Beacons/DropBeacon/CustomEventDropBeacon.swift

@@ -0,0 +1,44 @@
+//
+//  Copyright © 2024 IBM Corp. All rights reserved.
+//
+
+import Foundation
+
+///
+/// CustomEvent dropped beacon class
+///
+public class CustomEventDropBeacon: DropBeacon {
+    var eventName: String
+    var view: String?
+    var errorCount: Int?
+    var errorMessage: String?
+    var customMetric: String?
+
+    init(timestamp: Instana.Types.Milliseconds, eventName: String, view: String?,
+         errorCount: Int?, errorMessage: String?, customMetric: String?) {
+        self.eventName = eventName
+        self.view = view
+        self.errorCount = errorCount
+        self.errorMessage = errorMessage
+        self.customMetric = customMetric
+        super.init(timestamp: timestamp)
+    }
+
+    override func getKey() -> String {
+        let view1 = view ?? ""
+        let errorMessage1 = errorMessage ?? ""
+        let errorCount1 = errorCount ?? 0
+        return "\(eventName)|\(errorMessage1)|\(errorCount1)|\(view1)"
+    }
+
+    override func toString() -> String? {
+        let view1 = view ?? ""
+        let errorMessage1 = errorMessage ?? ""
+        let errorCount1 = errorCount ?? 0
+        let customMetric1 = customMetric ?? ""
+        let zInfoExtra = ["eventName": eventName, "errorMessage": validateLength(errorMessage1, maxLen: 200),
+                          "customMetric": validateLength(customMetric1, maxLen: 100),
+                          "view": view1, "errorCount": errorCount1] as [String: Any]
+        return convertToString(type: "CUSTOM_EVENT", subDict: zInfoExtra)
+    }
+}

Sources/InstanaAgent/Beacons/DropBeacon/DropBeacon.swift

@@ -0,0 +1,61 @@
+//
+//  Copyright © 2024 IBM Corp. All rights reserved.
+//
+
+import Foundation
+
+///
+/// Base class for dropped beacon
+///
+///
+public class DropBeacon {
+    var count: Int
+    var timeMin: Instana.Types.Milliseconds
+    var timeMax: Instana.Types.Milliseconds
+
+    init(timestamp: Instana.Types.Milliseconds) {
+        count = 1
+        timeMin = timestamp
+        timeMax = timestamp
+    }
+
+    func getKey() -> String {
+        return "dropBeaconPlaceholderKey"
+    }
+
+    func toString() -> String? {
+        return nil
+    }
+
+    func dictionaryToJsonString(_ dict: [String: Any]?, needSort: Bool = true) -> String? {
+        guard let dict = dict else {
+            return nil
+        }
+        do {
+            let options: JSONSerialization.WritingOptions = needSort ? [.sortedKeys] : []
+            let jsonData = try JSONSerialization.data(withJSONObject: dict, options: options)
+            if let jsonString = String(data: jsonData, encoding: .utf8) {
+                return validateLength(jsonString)
+            }
+        } catch {
+            Instana.current?.session.logger.add("Error converting dictionary to JSON: \(error.localizedDescription)")
+        }
+        return nil
+    }
+
+    func convertToString(type: String, subDict: [String: Any]) -> String? {
+        let zInfoBase = ["tMin": timeMin, "tMax": timeMax]
+        let zInfoDict = subDict.reduce(into: zInfoBase) { result, element in
+            result[element.key] = element.value
+        }
+        let dict = ["type": type, "count": count, "zInfo": zInfoDict] as [String: Any]
+        return dictionaryToJsonString(dict)
+    }
+
+    public func validateLength(_ str: String, maxLen: Int = 1024) -> String {
+        if str.count <= maxLen {
+            return str
+        }
+        return str.prefix(maxLen - 3) + "..."
+    }
+}

Sources/InstanaAgent/Beacons/DropBeacon/DropBeaconHandler.swift

@@ -0,0 +1,129 @@
+//
+//  Copyright © 2024 IBM Corp. All rights reserved.
+//
+
+import Foundation
+
+///
+/// A handler for beacons that were dropped because the maximum beacon send limit was reached.
+/// This will sample the dropped beacons and attempt to resend them as a custom event, once the
+/// limit is no longer exceeded.
+///
+public class DropBeaconHandler {
+    var httpUniqueMap: [String: DropBeacon]
+    var viewUniqueMap: [String: DropBeacon]
+    var customUniqueMap: [String: DropBeacon]
+    var MIN_BEACONS_REQUIRED = 2
+    let SAMPLING_BEACON_LIMIT = 5
+    var droppingStartTime: Instana.Types.Milliseconds
+    var droppingStartView: String?
+
+    init() {
+        httpUniqueMap = [String: DropBeacon]()
+        viewUniqueMap = [String: DropBeacon]()
+        customUniqueMap = [String: DropBeacon]()
+        droppingStartTime = 0
+        droppingStartView = nil
+    }
+
+    func addBeaconToDropHandler(beacon: Beacon) {
+        guard let extractedBeacon = beacon.extractDropBeaconValues() else {
+            return
+        }
+
+        if droppingStartTime == 0 {
+            droppingStartTime = Date().millisecondsSince1970
+        }
+
+        let key = extractedBeacon.getKey()
+        if extractedBeacon is HTTPDropBeacon {
+            saveDroppedBeacons(dropBeacon: extractedBeacon, key: key, uniqueMap: &httpUniqueMap)
+        } else if extractedBeacon is ViewDropBeacon {
+            saveDroppedBeacons(dropBeacon: extractedBeacon, key: key, uniqueMap: &viewUniqueMap)
+        } else if extractedBeacon is CustomEventDropBeacon {
+            saveDroppedBeacons(dropBeacon: extractedBeacon, key: key, uniqueMap: &customUniqueMap)
+        }
+
+        if droppingStartView == nil {
+            droppingStartView = beacon.viewName
+        }
+    }
+
+    func mergeDroppedBeacons() -> CustomBeacon? {
+        if droppingStartTime == 0 {
+            // no dropped beacons
+            return nil
+        }
+
+        var totalDropBeaconCount = 0
+        var mergedBeaconsMap = [String: String]()
+        totalDropBeaconCount += mergeDroppedBeacons(uniqueMap: httpUniqueMap,
+                                                    keyPrefix: "HTTP", mergedBeacons: &mergedBeaconsMap)
+        totalDropBeaconCount += mergeDroppedBeacons(uniqueMap: viewUniqueMap,
+                                                    keyPrefix: "VIEW", mergedBeacons: &mergedBeaconsMap)
+        totalDropBeaconCount += mergeDroppedBeacons(uniqueMap: customUniqueMap,
+                                                    keyPrefix: "CUSTOM_EVENT", mergedBeacons: &mergedBeaconsMap)
+
+        guard totalDropBeaconCount > 0 else {
+            reset() // Throw away accumulated dropped beacons if there are not many
+            return nil
+        }
+
+        let mergedBeacons = CustomBeacon(timestamp: droppingStartTime,
+                                         name: "INSTANA_DROPPED_BEACON_SAMPLE",
+                                         metaData: mergedBeaconsMap,
+                                         viewName: droppingStartView,
+                                         customMetric: Double(totalDropBeaconCount),
+                                         eventType: "beacon-drop")
+
+        reset() // Prepare for next round, might throw away some unsent beacons
+        return mergedBeacons
+    }
+
+    private func reset() {
+        droppingStartTime = 0
+        droppingStartView = nil
+        httpUniqueMap = [String: DropBeacon]()
+        viewUniqueMap = [String: DropBeacon]()
+        customUniqueMap = [String: DropBeacon]()
+    }
+
+    private func saveDroppedBeacons(dropBeacon: DropBeacon, key: String, uniqueMap: inout [String: DropBeacon]) {
+        if let existingBeacon = uniqueMap[key] {
+            existingBeacon.count += 1
+            if dropBeacon.timeMin < existingBeacon.timeMin {
+                existingBeacon.timeMin = dropBeacon.timeMin
+            }
+            if dropBeacon.timeMax > existingBeacon.timeMax {
+                existingBeacon.timeMax = dropBeacon.timeMax
+            }
+        } else {
+            uniqueMap[key] = dropBeacon
+        }
+    }
+
+    private func mergeDroppedBeacons(uniqueMap: [String: DropBeacon], keyPrefix: String,
+                                     mergedBeacons: inout [String: String]) -> Int {
+        let totalDropBeaconCount = uniqueMap.reduce(into: 0) { result, entry in
+            result += entry.value.count
+        }
+
+        if totalDropBeaconCount > MIN_BEACONS_REQUIRED {
+            // Though only maximum SAMPLING_BEACON_LIMIT beacons are collected,
+            // totalDropBeaconCount includes the not sampled beacons.
+            let descendingDropBeacons = uniqueMap.sorted { $0.value.count > $1.value.count }.prefix(SAMPLING_BEACON_LIMIT)
+            for (_, entryValue) in descendingDropBeacons {
+                let key = generateKey(prefix: keyPrefix)
+                mergedBeacons[key] = entryValue.toString()
+            }
+            return totalDropBeaconCount
+        }
+        return 0
+    }
+
+    private func generateKey(prefix: String) -> String {
+        let chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+        let randomStr = String((0 ..< 6).map { _ in chars.randomElement()! })
+        return "\(prefix)-\(randomStr)"
+    }
+}