為特定應用程式程式碼新增自訂監控功能

iOS 以上版本 Android 網頁版 Flutter

Performance Monitoring 會收集「追蹤記錄」，協助您監控應用程式效能。追蹤記錄是指在應用程式中兩個時間點之間擷取的效能資料報表。

您可以自行建立追蹤記錄，監控與應用程式中特定程式碼相關聯的效能資料。透過自訂程式碼追蹤記錄，您可以評估應用程式完成特定工作或一組任務所需的時間，例如載入一組圖片或查詢資料庫。

自訂程式碼追蹤記錄的預設指標為「持續時間」(追蹤記錄開始與停止點之間的時間)，但您也可以新增自訂指標。

在程式碼中，請使用 Performance Monitoring SDK 提供的 API 定義自訂程式碼追蹤記錄的開頭和結尾。 自訂程式碼追蹤記錄建立後，就能隨時啟動，而且符合執行緒安全規範。

由於這些追蹤記錄的預設指標是「時間長度」，因此有時也稱為「時間長度追蹤記錄」。

您可以在追蹤記錄表格的「Custom traces」子分頁中查看這些追蹤記錄的資料，這個子分頁位於「Performance」資訊主頁底部 (本頁稍後將說明如何使用主控台)。

注意： 太快啟動和停止追蹤記錄會耗用大量資源，因此請避免以高頻率建立自訂程式碼追蹤記錄，例如遊戲中每個影格一次。

預設屬性、自訂屬性和自訂指標

如果是自訂程式碼追蹤記錄，Performance Monitoring 會自動記錄預設屬性 (常見的中繼資料，例如應用程式版本、國家/地區、裝置等)，您可以在 Firebase 控制台篩選追蹤記錄的資料。您也可以新增及監控自訂屬性 (例如遊戲層級或使用者屬性)。

您可以進一步設定自訂程式碼追蹤記錄，針對出現在追蹤記錄範圍內的效能相關事件記錄自訂指標。例如，您可以建立自訂指標，計算快取命中和失敗的次數，或 UI 在一段明顯的時間範圍內沒有回應的次數。

自訂屬性和自訂指標會顯示在 Firebase 控制台中，以及追蹤記錄的預設屬性和預設指標。

「屬性」是字串值，可協助您在控制台中篩選及區隔資料。「指標」是指可以隨著時間繪製圖表及測量的數值值。

新增自訂程式碼追蹤記錄

使用 Performance Monitoring Trace API (Swift | Obj-C) 新增自訂程式碼追蹤記錄，以便監控特定應用程式程式碼。

注意事項：

• 一個應用程式可以有多個自訂程式碼追蹤記錄。
• 您可以同時執行多個自訂程式碼追蹤記錄。
• 自訂程式碼追蹤記錄的名稱必須符合下列規定：開頭或結尾不得為空白字元、開頭不為底線 (_) 字元，且長度上限為 100 個字元。
• 自訂程式碼追蹤記錄支援新增自訂指標和自訂屬性。

如要啟動及停止自訂程式碼追蹤記錄，請使用類似以下的程式碼行來包裝您要追蹤的程式碼：

Swift

注意：這項 Firebase 產品不適用於 macOS、Mac Catalyst 和 watchOS 目標。

// Add the Performance Monitoring module to your header
import FirebasePerformance

let trace = Performance.startTrace(name: "CUSTOM_TRACE_NAME")

// code that you want to trace

trace.stop()

Objective-C

注意：這項 Firebase 產品不適用於 macOS、Mac Catalyst 和 watchOS 目標。

// Add the Performance Monitoring module to your header
@import FirebasePerformance;

FIRTrace *trace = [FIRPerformance startTraceWithName:@"CUSTOM_TRACE_NAME"];

// code that you want to trace

[trace stop];

在自訂程式碼追蹤記錄中新增自訂指標

使用 Performance Monitoring Trace API (Swift | Obj-C) 將自訂指標新增至自訂程式碼追蹤記錄。

注意事項：

• 自訂指標的名稱必須符合下列規定：開頭或結尾不得為空白字元、開頭不加上底線 (_) 字元，且長度上限為 100 個字元。
• 每個自訂程式碼追蹤記錄最多可記錄 32 個指標 (包括預設的 Duration 指標)。

如要新增自訂指標，請在每次事件發生時新增一行類似下方的程式碼。舉例來說，這個自訂指標會計算應用程式內的成效相關事件，例如快取命中或重試事件。

Swift

注意：這項 Firebase 產品不適用於 macOS、Mac Catalyst 和 watchOS 目標。

let trace = Performance.startTrace(name: "CUSTOM_TRACE_NAME")

trace.incrementMetric(named:"EVENT_NAME", by: 1)
// code that you want to trace (and log custom metrics)

trace.stop()

Objective-C

注意：這項 Firebase 產品不適用於 macOS、Mac Catalyst 和 watchOS 目標。

FIRTrace *trace = [FIRPerformance startTraceWithName:@"CUSTOM_TRACE_NAME"];

[trace incrementMetric:@"EVENT_NAME" byInt:1];
// code that you want to trace (and log custom metrics)

[trace stop];

建立自訂程式碼追蹤記錄的自訂屬性

使用 Performance Monitoring Trace API (Swift | Obj-C) 將自訂屬性新增至自訂程式碼追蹤記錄。

如要使用自訂屬性，請在應用程式中加入用來定義屬性的程式碼，並將其與特定自訂程式碼追蹤記錄建立關聯。從追蹤記錄開始到追蹤記錄停止的時間點之間，您隨時可以設定自訂屬性。

注意事項：

• 自訂屬性名稱必須符合下列規定：

  • 開頭或結尾無空白，無前置底線 (_) 字元
  • 不能有空格
  • 長度上限為 32 個半形字元
  • 名稱可使用的字元包括 A-Z、a-z 和 _。

• 每個自訂程式碼追蹤記錄最多可記錄 5 個自訂屬性。

• 請確認自訂屬性不含任何 Google 可識別個人身分的資訊。

  進一步瞭解這項規範

  收集使用者資料：Performance Monitoring 本身不會收集任何個人識別資訊 (PII)，例如姓名、電子郵件地址或電話號碼。開發人員可以針對自訂程式碼追蹤記錄建立自訂屬性，使用 Performance Monitoring 收集額外資料。透過 Performance Monitoring 收集的資料不得包含可供 Google 識別個人身分的資訊。

  以下是「不含」個人識別資訊的記錄訊息範例：

  trace.putAttribute("experiment", "A");

  以下範例包含包含個人識別資訊 (請勿用於此應用程式的自訂屬性此類型)：

  trace.putAttribute("email", user.getEmailAddress());

  如有任何資料曝露在個人識別資訊中，我們可能會將其刪除，恕不另行通知。

Swift

注意：這項 Firebase 產品不適用於 macOS、Mac Catalyst 和 watchOS 目標。

let trace = Performance.startTrace(name: "CUSTOM_TRACE_NAME")

trace.setValue("A", forAttribute: "experiment")

// Update scenario.
trace.setValue("B", forAttribute: "experiment")

// Reading scenario.
let experimentValue:String? = trace.valueForAttribute("experiment")

// Delete scenario.
trace.removeAttribute("experiment")

// Read attributes.
let attributes:[String, String] = trace.attributes;

Objective-C

注意：這項 Firebase 產品不適用於 macOS、Mac Catalyst 和 watchOS 目標。

FIRTrace *trace = [FIRPerformance startTraceWithName:@"CUSTOM_TRACE_NAME"];

[trace setValue:@"A" forAttribute:@"experiment"];

// Update scenario.
[trace setValue:@"B" forAttribute:@"experiment"];

// Reading scenario.
NSString *experimentValue = [trace valueForAttribute:@"experiment"];

// Delete scenario.
[trace removeAttribute:@"experiment"];

// Read attributes.
NSDictionary <NSString *, NSString *> *attributes = [trace attributes];

追蹤、查看及篩選成效資料

在資訊主頁中追蹤特定指標

如要瞭解主要指標的趨勢變化，請將這些指標新增至「效能」資訊主頁頂端的指標看板。您可以查看逐週變化，或確認近期程式碼變更是否有助於提升效能，藉此快速找出迴歸問題。

如要在指標板中新增指標，請按照下列步驟操作：

1. 前往 Firebase 控制台的「Performance」(效能) 資訊主頁。
2. 按一下空白指標資訊卡，然後選取要加入資訊主面板的現有指標。
3. 按一下已填入指標資訊卡上的 ，即可查看更多選項，例如取代或移除指標。

指標板會顯示一段時間內收集到的指標資料，以圖像形式和數值百分比變化。

進一步瞭解如何使用資訊主頁。

查看追蹤記錄和相關資料

如要查看追蹤記錄，請前往 Firebase 控制台的「Performance」(效能) 資訊主頁，向下捲動至追蹤記錄表格，然後按一下適當的子分頁標籤。資料表會顯示每筆追蹤記錄的熱門指標，您甚至可以根據特定指標的百分比變化來排序清單。

Performance Monitoring 提供 Firebase 控制台的疑難排解頁面，該頁面會醒目顯示指標變更，讓您輕鬆快速解決，並盡可能減少對應用程式和使用者造成的影響。您可以透過疑難排解頁面瞭解潛在的效能問題，例如在下列情況下使用：

• 您在資訊主頁上選取相關指標後，發現出現大幅差異。
• 在追蹤記錄表格中，在頂端顯示最大的差異，而且百分比變化有顯著變化。
• 您會在出現效能問題時收到電子郵件快訊，

您可以透過下列方式存取疑難排解頁面：

• 在指標資訊主頁中，按一下「查看指標詳細資料」按鈕。
• 在任何指標資訊卡上，選取「 => 查看詳細資料」。疑難排解頁面會顯示所選指標的相關資訊。
• 在追蹤記錄表格中，按一下追蹤記錄名稱或該追蹤記錄列中的任何指標值。
• 按一下電子郵件快訊中的「立即調查」。

只要點選追蹤記錄表格中的追蹤記錄名稱，即可進一步查看感興趣的指標。按一下「篩選器」按鈕，即可按屬性篩選資料，例如：

• 依「應用程式版本」篩選，即可查看過去或最新版本的資料
• 依「裝置」篩選，瞭解舊版裝置如何處理您的應用程式
• 依「國家/地區」篩選，確保資料庫位置不會影響特定區域

進一步瞭解如何查看追蹤記錄資料。

後續步驟

• 進一步瞭解如何使用屬性來檢查成效資料。

• 進一步瞭解如何在 Firebase 控制台中追蹤效能問題。

• 為會降低應用程式效能的程式碼變更設定快訊。舉例來說，如果特定自訂程式碼追蹤記錄的時間長度超過您設定的門檻，您可以設定團隊的電子郵件快訊。

• 查看使用者工作階段的詳細報表，透過時間軸內容，查看同一個工作階段期間收集到的其他追蹤記錄中的特定追蹤記錄。