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

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

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

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

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

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

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

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

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

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

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

新增自訂程式碼追蹤記錄

使用 Performance Monitoring Trace API 新增自訂程式碼追蹤記錄，以監控特定應用程式程式碼。

注意事項：

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

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

Web

import { trace } from "firebase/performance";

const t = trace(perf, "CUSTOM_TRACE_NAME");
t.start();

// Code that you want to trace 
// ...

t.stop();
perf_add_custom_trace.js

Web

const trace = perf.trace("CUSTOM_TRACE_NAME");
trace.start();

// Code that you want to trace 
// ...

trace.stop();
index.js

使用 User Timing API 新增自訂程式碼追蹤記錄

除了 Performance Monitoring Trace API，您也可以使用瀏覽器的原生 User Timing API 新增自訂程式碼追蹤記錄。Performance Monitoring SDK 會自動擷取使用這個 API 測量的追蹤記錄時間長度。如果您偏好以非同步方式載入 Performance Monitoring SDK，則使用 User Timing API 會特別有幫助。SDK 初始化後，SDK 會記錄載入之前發生的測量結果。

若要使用這項功能，請用 User Timing 標記包裝想要追蹤的程式碼：

Web

const performance = window.performance;

performance.mark("measurementStart");

// Code that you want to trace 
// ...

performance.mark("measurementStop");
performance.measure("customTraceName", "measurementStart", "measurementStop");
perf_user_timing_marks.js

Web

const performance = window.performance;

performance.mark("measurementStart");

// Code that you want to trace 
// ...

performance.mark("measurementStop");
performance.measure("customTraceName", "measurementStart", "measurementStop");
index.js

請注意，上述範例中的 performance 是指瀏覽器的 window.performance 物件。

使用 User Timing API 時，無法將自訂指標和屬性新增至自訂程式碼追蹤記錄。如果您想將這些自訂元素新增至自訂程式碼追蹤記錄，請使用 Performance Monitoring Trace API。

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

使用 Performance Monitoring 的 Trace API，將自訂指標新增至自訂程式碼追蹤記錄。

注意事項：

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

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

Web

import { trace } from "firebase/performance";

async function getInventory(inventoryIds) {
  const t = trace(perf, "inventoryRetrieval");

  // Tracks the number of IDs fetched (the metric could help you to optimize in the future)
  t.incrementMetric("numberOfIds", inventoryIds.length);

  // Measures the time it takes to request inventory based on the amount of inventory
  t.start();
  const inventoryData = await retrieveInventory(inventoryIds);
  t.stop();

  return inventoryData;
}
perf_add_custom_metrics.js

Web

async function getInventory(inventoryIds) {
  const trace = perf.trace("inventoryRetrieval");

  // Tracks the number of IDs fetched (the metric could help you to optimize in the future)
  trace.incrementMetric("numberOfIds", inventoryIds.length);

  // Measures the time it takes to request inventory based on the amount of inventory
  trace.start();
  const inventoryData = await retrieveInventory(inventoryIds);
  trace.stop();

  return inventoryData;
}
index.js

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

使用 Performance Monitoring Trace API，將自訂屬性新增至自訂程式碼追蹤記錄。

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

注意事項：

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

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

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

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

    進一步瞭解這項規範

Web

import { trace } from "firebase/performance";

const t = trace(perf, "test_trace");
t.putAttribute("experiment", "A");

// Update scenario
t.putAttribute("experiment", "B");

// Reading scenario
const experimentValue = t.getAttribute("experiment");

// Delete scenario
t.removeAttribute("experiment");

// Read attributes
const traceAttributes = t.getAttributes();
perf_add_custom_attributes.js

Web

const trace = perf.trace("test_trace");
trace.putAttribute("experiment", "A");

// Update scenario
trace.putAttribute("experiment", "B");

// Reading scenario
const experimentValue = trace.getAttribute("experiment");

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

// Read attributes
const traceAttributes = trace.getAttributes();
index.js

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

如要查看即時效能資料，請確認您的應用程式使用與即時資料處理相容的 Performance Monitoring SDK 版本。進一步瞭解即時成效資料。

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

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

Firebase Performance Monitoring 資訊主頁中的指標看板

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

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

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

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

查看追蹤記錄和相關資料

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

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

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

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

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

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

圖片：依屬性篩選 Firebase Performance Monitoring 資料
  • 依「網頁網址」篩選，查看網站中特定網頁的資料
  • 依「有效連線類型」篩選，瞭解 3G 連線對應用程式的影響
  • 依「國家/地區」篩選，確保資料庫位置不會影響特定區域

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

後續步驟

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

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

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