iOS API

Instana iOS 代理程式 API

Instana iOS 代理程式 API

下一節說明 Instana iOS 代理程式的用法。 Instana 的 iOS 代理程式可以透過這裡說明的 Instana 類別方法來使用。

設定

呼叫設定功能，以在 didFinishLaunchingWithOptions 中提早起始設定 Instana iOS 代理程式。請勿延遲啟動 Instana。請務必在應用程式啟動之後立即呼叫設定。您可以使用 Instana.collectionEnabled 旗標來延遲啟用或停用 Instana。

static func setup(key: String, reportingURL: URL, httpCaptureConfig: HTTPCaptureConfig = .automatic)

配置參數

參數	說明
`key` (`String`)	Instana 監視配置金鑰。
`reportingURL` (`URL`)	指向要將監視資料傳送至其中的 Instana 實例的 URL。
`httpCaptureConfig` `HTTPCaptureConfig` (選用)	依預設，會自動擷取 HTTP 要求和回應。若要停用自動監視，請將此參數設為 `manual` ，或將這兩種模式與 `automaticAndManual` HTTP 擷取配置一起使用。若要關閉 HTTP 階段作業監視，您可以傳遞 `none`。
`collectionEnabled` (`Bool`，選用)	依預設，會隨設定開啟資料收集。若要設定 Instana ，但忽略任何資料收集，請在設定中將此參數設為 `false` 。在需要使用者同意才能代理程式收集資料的情況下，此參數非常有用。預設值為 `true`。
`enableCrashReporting` (`Bool`，選用)	(技術預覽) 依預設，會在設定中停用資料收集。稍後可以使用此內容來啟用資料收集，這可讓應用程式開始收集 Instana 損毀資料。在代理程式可以收集損毀資料之前需要明確使用者同意的實務範例中，此內容最有用。預設值為 `false`。
`slowSendInterval` (`Double`，選用)	此參數透過提供有效的正數 (以秒為單位，範圍從 2-3600) ，在信標傳送失敗時啟用慢速傳送模式特性。預設值為 `0.0`，表示已停用慢速傳送模式。

範例

import InstanaAgent

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    Instana.setup(key: "<Your Instana Key>", reportingURL: URL(string: "<Your Instana instance URL>")!)
    ....
    return true
}

下列範例會擷取具有索引鍵 X-Key 或 X-KEY 的 HTTP 標頭欄位，並使用預設 automatic HTTP 擷取配置。若要變更預設值，請使用下列指令:

let options = InstanaSetupOptions(httpCaptureConfig: .manual)
Instana.setup(key: <Your Key>, reportingURL: <Your Instana URL>, options: options)

現行配置

Instana 類別物件具有一些內容，可擷取現行配置設定:

內容	說明
`key` (`String`，選用)	Instana 監視配置金鑰。
`reportingURL` (`URL`，選用)	指向要將監視資料傳送至其中的 Instana 實例的 URL。

範例

let key = Instana.key
let url = Instana.reportingURL

階段作業 ID

每一個 Instana 代理程式實例都有唯一的階段作業 ID ，您可以在應用程式中用於其他用途。

內容	說明
`sessionID` (`String`，選用)	現行階段作業 ID。將在設定程序內建立此階段作業 ID。

範例

let sessionID = Instana.sessionID

自動 HTTP 監視

依預設，會自動擷取 HTTP 階段作業。 Instana iOS 代理程式使用 Foundation 的 NSURLProtocol 來監視 HTTP 要求及回應。若要在 NSURLSession 中使用 NSURLProtocol 某個方法來自動觀察所有 NSURLSession 。若要拒絕自動 HTTP 階段作業監視，您必須手動擷取每個要求及回應。

手動 HTTP 監視

如果要手動擷取 HTTP 階段作業，您必須使用 httpCaptureConfig: .manual 來設定 Instana ，並使用說明的對應功能。您可以使用 URLRequest 或 URL來手動擷取 HTTP 要求和回應。

自動及手動 HTTP 監視

如果要自動和手動擷取 HTTP 階段作業，您必須使用 httpCaptureConfig: .automaticAndManual來設定 Instana。您可以使用自動檢測或選擇性地手動擷取 HTTP 要求或回應。

開始擷取 (URLRequest)

此函數會針對 URLRequest 及選用視圖名稱啟動 http 擷取。會傳回 HTTPMarker 物件，您稍後需要該物件來設定 HTTP 回應的結果。

static func startCapture(_ request: URLRequest?, viewName: String? = nil) -> HTTPMarker

配置參數

參數	說明
`request` (`URLRequest`)	要擷取的 URLRequest。
`viewName` (`String`，選用)	與此要求相關之可見視圖的選用名稱

傳回: 用來設定 HTTP 回應結果的 HTTP 標記 (HTTP 狀態碼、大小、錯誤)。

開始擷取 (URL)

此函數會啟動 URL、HTTP 方法及選用視圖名稱的 HTTP 擷取。會傳回 HTTPMarker 物件，您稍後需要該物件來設定 HTTP 回應的結果。

static func startCapture(url: URL, method: String, viewName: String? = nil) -> HTTPMarker

配置參數

參數	說明
`url` (`URL`)	要擷取的 URL。
`method` (`String`)	要求的 HTTP 方法。
`viewName` (`String`，選用)	與此要求相關之可見視圖的選用名稱

傳回: 用來設定 HTTP 回應結果的 HTTP 標記 (HTTP 狀態碼、大小、錯誤)。

設定 HTTP 回應大小

當決定回應大小時，在 HTTPMarker 上呼叫此方法。

func set(responseSize: Instana.Types.HTTPSize)

配置參數

參數	說明
`responseSize` (`HTTPSize`)	包含 `headerBytes`、 `bodyBytes`、 `bodyBytesAfterDecoding` 的 httpSize 物件

附註: 在您呼叫 finish 或 cancel 之後，請確定您沒有在 HTTPMarker 上呼叫任何方法

HTTP 回應大小

您可以使用下列起始設定元來建立 HTTPMarker.Size :

init(response: URLResponse, transactionMetrics: [URLSessionTaskTransactionMetrics]?)

配置參數

參數	說明
`response` (`URLResponse`)	URLResponse 物件
`transactionMetrics` (`[URLSessionTaskTransactionMetrics]`，選用)	具有 `URLSessionTaskTransactionMetrics` 的選用陣列

您也可以直接傳遞大小值作為參數來建立 HTTPMarker.Size 物件

HTTPMarker.Size(header: Instana.Types.Bytes, body: Instana.Types.Bytes, bodyAfterDecoding: Instana.Types.Bytes)

完成擷取 (URLResponse)

在使用 URLResponse 及選用 Error 完成要求之後，立即呼叫 finish on HTTPMarker 。

func finish(response: URLResponse?, error: Error?)

完成擷取 (HTTPCaptureResult)

或者，您可以使用 HTTPCaptureResult 來完成擷取。

let size = HTTPMarker.Size(header: 123, body: 1024, bodyAfterDecoding: 2048)
let result = HTTPCaptureResult(statusCode: statusCode, backendTracingID: "Instana-backend-tracing-id", responseSize: size, error: error)
marker.finish(result: result)

取消擷取

如果在完成之前取消要求，請在 HTTPMarker 上呼叫此方法。當您呼叫 cancel時，狀態會在內部設為失敗，且具有 NSURLErrorCancelled 。

func cancel()

完成手動 HTTP 監視範例 (URLResponse)

let marker = Instana.startCapture(request, viewName: "User: Details")
URLSession.shared.dataTask(with: request) { data, response, error in
    marker.finish(response: response, error: error)
}.resume()

您也可以透過 URLSessionDelegate 手動設定 HTTP 回應大小，如下列範例所示 (在呼叫完成或取消之前):

func urlSession(_ session: URLSession, task: URLSessionTask, didFinishCollecting metrics: URLSessionTaskMetrics) {
    guard let response = task.response else { return }
    marker.set(responseSize: HTTPMarker.Size(response: response, transactionMetrics: metrics.transactionMetrics))
}

完成手動 HTTP 監視範例 (URL)

let url = URL(string: "https://www.example.com/user/123/details")!
let marker = Instana.startCapture(url: url, method: "GET", viewName: "Home")
YourNetworkManager(url: url, method: "GET") { (statusCode, error) in
    let size = HTTPMarker.Size(header: 123, body: 1024, bodyAfterDecoding: 2048) // optionally
    let backendTracingID = "Instana-backend-tracing-id" // optionally
    let result = HTTPCaptureResult(statusCode: statusCode, backendTracingID: backendTracingID, responseSize: size, error: error)
    marker.finish(result: result)
}.resume()

視圖

Instana 可以依邏輯視圖將應用程式度量值分段。若要這樣做，它需要提示使用者目前正在查看的視圖。此視圖名稱可以透過 setView(name: String)來設定。視圖名稱會連接至所有受監視的信標，直到您以另一個名稱再次呼叫 setView 為止。一般而言，我們建議不要使用「類別」之類的技術或通用名稱 (例如 WebViewController) 以定義視圖。建議使用可讀取的視圖名稱。例如 product detail page 或 payment selection。這會導致與實際現有程式碼有直接關係的頁面減少。建議在 viewDidAppear中設定視圖名稱。設定視圖名稱也會啟用 Instana ，以追蹤除了頁面載入之外的頁面轉移。

當您的應用程式變更狀態 (例如，從作用中變更為非作用中或背景) 時，會自動更新視圖名稱。當您的應用程式處於非作用中狀態 (接收 SMS 時) 時，視圖名稱將會是 Inactive ，並且在您的應用程式離開前景之後將會設為 Background 。

static func setView(name: String)

配置參數

參數	說明
`name` (`String`)	視圖的名稱。

範例

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    Instana.setView(name: "User: Details")
}

若要取得現行視圖名稱，您可以使用類別變數 viewName。視您的應用程式狀態而定，視圖名稱的值可能是 Inactive 或 Background 。

內容	說明
`viewName` (`String`，選用)	透過 `setView(name:)`設定的現行視圖名稱。

範例

let viewName = Instana.viewName

識別使用者

使用者特定資訊可以選擇性地與傳輸至 Instana 的資料一起傳送。然後可以使用此資訊來解除鎖定其他功能，例如:

計算受錯誤影響的使用者數目，
過濾特定使用者的資料
以查看哪個使用者起始視圖變更或 HTTP 要求。

依預設， Instana 不會將任何使用者識別資訊關聯至信標。在選擇這樣做時，請注意個別的資料保護法。我們通常建議透過使用者 ID 來識別使用者。對於 Instana ，這是完全透通的 String ，僅用於計算特定度量值。 userName 和 userEmail 也可以用來存取更多過濾器，以及更愉快地呈現使用者資訊。

在您處理匿名使用者因而無法存取使用者 ID 的情況下，您可以選擇使用階段作業 ID。階段作業 ID 在過濾資料時沒有使用者 ID 那麼有用，但它們是計算受影響/唯一使用者度量值的良好指標。建議設定使用者名稱 (例如 Anonymous ) ，以明確區分已鑑別與未經鑑別的使用者。階段作業 ID 可以是機密資料 (視使用的架構/平台而定)。 請考量雜湊階段作業 ID ，以避免將資料傳輸至可授與存取權的 Instana。

請務必注意，已傳輸至 Instana 伺服器的資料無法追溯更新。基於此原因，請務必在應用程式啟動程序中儘快呼叫此 API。

static func setUser(id: String, email: String?, name: String?)

配置參數

參數	說明
`id` (`String`)	使用者的 ID。
`email` (`String`，選用)	使用者的電子郵件位址。
`name` (`String`，選用)	使用者的名稱。

您可以針對不想設定的值傳遞 nil 。

範例

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
     Instana.setUser(id: someID, email: "email@example.com", name: "John")
     return true
}

或者，您可以個別設定使用者內容。

使用者 ID

設定使用者 ID

static func setUser(id: String)

配置參數

參數	說明
`id` (`String`)	使用者的 ID。

使用者電子郵件位址

設定使用者電子郵件位址

static func setUser(email: String)

配置參數

參數	說明
`email` (`String`)	使用者的電子郵件位址。

使用者名稱

設定使用者的名稱

static func setUser(name: String)

參數

參數	說明
`name` (`String`)	使用者的名稱。

meta 資料

附加至所傳輸資料的 meta 資料資訊。請考量使用來追蹤使用者介面配置值、設定、特性旗標 ... 任何可能有助於分析的其他環境定義。您應該在應用程式啟動程序中設定 meta 資料，以將索引鍵或值指派給所有傳輸的資料。

static func setMeta(value: String, key: String)

參數

參數	說明
`value` (`String`)	您要新增為 meta 資料之鍵值組的 `value` 。
`key` (`String`)	您要新增為 meta 資料之鍵值組的 `key` 。

範例

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
    Instana.setMeta(value: "ReactNative", key: "Platform")
    Instana.setMeta(value: "DEBUG", key: "Environment")
    return true
}

從監視排除 URLSession

您可以忽略自訂 URLSession ，使其不受 Instana iOS 代理程式監視。

static func ignore(_ session: URLSession)

配置參數

參數	說明
`session` (`URLSession`)	要從監視忽略的 URLSession。

範例

let session = URLSession(configuration: .default)
Instana.ignore(session)

從監視排除 URL

您可以忽略 URL 來拒絕符合給定正規表示式的 URL ，以防止傳輸至 Instana。使用此函數的一個良好範例是忽略包含任何機密資料 (例如密碼) 的所有 HTTP 要求。

static func setIgnoreURLs(matching regex: [NSRegularExpression])

配置參數

參數	說明
`regex` (`[NSRegularExpression]`)	符合您要忽略之 URL 的 `NSRegularExpression` 物件陣列。

範例

let regex = try! NSRegularExpression(pattern: "/.*(&|\?)password=.*/i")
Instana.setIgnoreURLs(matching: [regex])

該範例會忽略查詢中包含密碼的所有 URL。

或者，您可以忽略完整 URL ，例如:

Instana.setIgnore(urls: [URL(string: "https://www.example.com")!])

報告自訂事件

自訂事件可讓您將非標準活動、重要互動及自訂計時報告給 Instana。在分析未捕捉的錯誤 (瀏覽途徑) 及追蹤更多效能度量值時，它特別有用。

static func reportEvent(name: String, timestamp: Instana.Types.Milliseconds? = nil, duration: Instana.Types.Milliseconds? = nil, backendTracingID: String? = nil, error: Error? = nil, meta: [String: String]? = nil, viewName: String? = Instana.viewName)

配置參數

參數	說明
`name` (`String`)	定義應用程式中發生的會導致傳輸自訂信標的事件類型。
`timestamp` (`Int64`，選用)	事件啟動時的時間戳記 (毫秒)。如果您沒有提供時間戳記，我們會假設現在是時間戳記。如果您不提供時間戳記，但設定持續時間，則我們會從現在減去持續時間來計算時間戳記。 (timestamp = now-duration)
`duration` (`Int64`，選用)	事件持續多久的持續時間 (毫秒)。預設值為零
`backendTracingID` (`String`，選用)	用來建立此事件的後端追蹤的 ID。
`error` (`Error`，選用)	提供更多環境定義的錯誤物件。
`meta` (`[String: String]`，選用)	鍵值資料，僅針對此單一事件可用來將 meta 資料傳送至 Instana
`viewName` (`String`，選用)	您可以傳遞字串，將要求分組至視圖。如果您明確傳送零，則會忽略 viewName 。或者，您可以省略參數 `viewName` ，以使用您在 `setView(name: String)`中設定的現行視圖名稱)

範例

Instana.reportEvent(name: "Event-Name")
Instana.reportEvent(name: "Event-Name", viewName: "User: Details")
Instana.reportEvent(name: "Event-Name", timestamp: 1590149955086, duration: 124842, backendTracingID: "some-id", error: NSError(domain: "Some", code: -1, userInfo: nil), meta: ["Key": "Value"], viewName: "User: Details")

已啟用或停用收集

您可以在執行時期隨時啟用或停用資料收集。它會啟用資料收集的延遲啟動 (例如，在使用者同意之後)。

內容	說明
`collectionEnabled` (`Bool`)	啟用或停用資料收集的旗標

範例

Instana.collectionEnabled = true

啟用記載功能

Instana iOS 代理程式具有用於除錯的記載功能。只要在 Xcode 中新增環境變數 INSTANA_DEBUG_LOGLEVEL 。作為值，您必須傳遞記載層次的數字: 0 = 除錯資訊、警告和錯誤， 1 = 警告和錯誤， 2 => 僅限錯誤

編寫 URL 查詢參數

所收集 URL 中的查詢參數可能包含機密資料。因此， Instana iOS 代理程式支援應編寫其值之查詢參數索引鍵的正規表示式型樣規格。任何校訂的值都將取代為 <redacted>。在向 Instana 伺服器報告之前，會在 Instana 代理程式內進行編寫。因此，密鑰將無法到達 Instana 伺服器進行處理，且無法在使用者介面中進行分析或使用 Instana API 進行擷取。

依預設， Instana iOS 代理程式會配置三個正規表示式型樣的清單，以自動編寫索引鍵的查詢參數值: "password"、"key" 及 "secret"。編寫只會套用至自動監視的要求及其相關聯的日誌。未編寫手動監視的要求。

static func redactHTTPQuery(matching regex: [NSRegularExpression])

配置參數

參數	說明
`regex` (`[NSRegularExpression]`)	符合您要編寫的值之索引鍵的 `NSRegularExpression` 物件陣列。

範例

let regex = try! NSRegularExpression(pattern: #"pass(word|wort)"#)
Instana.redactHTTPQuery(matching: [regex])

此範例會編寫 HTTP 參數金鑰 "password" 或 "passwort" 的值。擷取的 URL https://example.com/accounts/?password=123&passwort=459 將收集並顯示為 https://example.com/accounts/?password=<redacted>&passwort=<redacted>。

附註: Instana iOS 代理程式不支援處理路徑參數 (/account/)/status) 或 matrix 參數 (/account;accountId=/status) 作為密鑰。

擷取 HTTP 標頭欄位

iOS 代理程式可以擷取 HTTP 要求及回應標頭。您可以使用正規表示式來定義 iOS 代理程式需要擷取的 HTTP 標頭欄位索引鍵。

public static func setCaptureHeaders(matching regex: [NSRegularExpression])

配置參數

參數	說明
`regex` (`[NSRegularExpression]`)	`NSRegularExpression` 物件的陣列，以符合您要擷取的 HTTP 要求/回應標頭的索引鍵。

範例

let regex = try! NSRegularExpression(pattern: #"X-Key"#, options: [.caseInsensitive])
Instana.setCaptureHeaders(matching: [regex])

此範例會擷取具有索引鍵 X-Key 或 X-KEY的 HTTP 標頭欄位。

慢速傳送模式

選用: 您可以開啟慢速傳送模式特性。

依預設，如果信標傳送失敗， Instana 代理程式會嘗試重新傳送信標，直到傳送成功為止。這在某些行動網路上並不奏效。透過啟用慢速傳送模式特性，信標傳送間隔會變更為指派給 slowSendInterval 參數的時間值。每一個傳送僅包含一個引標而非批次 (批次中最多 100 個引標)。 Instana 代理程式會保持慢速傳送模式，直到順利傳送一個引標為止。

slowSendInterval 的有效時間範圍是 2-3600 (秒)。

範例

import InstanaAgent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let options = InstanaSetupOptions(slowSendInterval: 60.0)
    if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
        // Error handling here
    }
    ....
    return true
}

使用者階段作業 ID

依預設，會追蹤使用者階段作業，且 ID 是隨機產生的「通用唯一 ID (UUID)」。安裝應用程式時，此 ID 保持不變。您可以使用 usiRefreshTimeIntervalInHrs 參數來配置使用者階段作業 ID 的有效期限。下列參數值指出使用者階段作業 ID 的狀態:

負數: 此值指出使用者階段作業 ID 永不到期。預設值為 -1。
正數: 此值表示在設定時間之後重新整理使用者階段作業 ID ，亦即產生並使用新的 UUID。
零: 以 0.0 表示的這個值表示已停用使用者階段作業 ID。

範例

import InstanaAgent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let options = InstanaSetupOptions(usiRefreshTimeIntervalInHrs: 24.0)
    if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
        // Error handling here
    }
    ....
    return true
}