將 Firebase Crashlytics 資料匯出至 BigQuery

您可以將 Firebase Crashlytics 資料匯出至 BigQuery，以進行進一步分析。BigQuery 讓您使用 BigQuery SQL 分析資料、匯出至其他雲端供應商，以及透過 Looker Studio 製作視覺化圖表和自訂資訊主頁。

匯出資料的用途

匯出至 BigQuery 的檔案包含原始當機資料，包括裝置類型、作業系統、例外狀況 (Android 應用程式) 或錯誤 (Apple 應用程式)，以及 Crashlytics 記錄和其他資料。您稍後可在本頁查看匯出的Crashlytics資料內容和資料表結構定義。

以下列舉幾個匯出資料的用途：Crashlytics

• 執行查詢
  您可以對 Crashlytics 資料執行查詢，產生報表，將當機事件資料匯總至更容易理解的摘要中。由於這些類型的報表無法在控制台的 Crashlytics 資訊主頁中取得，因此可做為補充資料，協助您分析及瞭解當機資料。Firebase本頁稍後會提供查詢範例。

• 使用 Looker Studio 範本
  Crashlytics 提供預先建構的 Looker Studio 範本 ，用於將匯出的資料視覺化。

• 建立檢視區塊
  使用 BigQuery UI 建立檢視區塊，也就是由 SQL 查詢定義的虛擬資料表。如需不同類型檢視區塊的詳細操作說明，以及如何建立檢視區塊，請參閱 BigQuery 說明文件。

• 將 Crashlytics 專屬資料與 Firebase 工作階段資料合併
  設定 Crashlytics 資料匯出功能時，您也可以匯出 Firebase 工作階段資料。運用這項工作階段資料，進一步瞭解未發生當機情形的使用者和工作階段。

將資料串流匯出至 BigQuery 的優點

根據預設，資料會每天批次匯出至 BigQuery。 此外，您也可以使用BigQuery串流功能，即時串流 Crashlytics 資料和 Firebase 工作階段。您可以使用這項功能處理任何需要即時資料的用途，例如在即時資訊主頁中呈現資訊、觀看發布作業的即時情況，或是監控會觸發快訊和自訂工作流程的應用程式問題。

啟用串流匯出至 BigQuery 時，您也會取得即時資料表 (除了批次資料表之外)。這兩種資料表都會有相同的資料集結構定義，但批次資料表和即時資料表之間有以下重要差異：

批次資料表適合長期分析及找出一段時間內的趨勢，因為系統會先永久儲存事件，再寫入資料表，且最多可回填 30 天的資料*。當我們將資料寫入即時資料表時，會立即將資料寫入 BigQuery，因此非常適合用於即時資訊主頁和自訂快訊。這兩個資料表可以透過縫合查詢合併，同時享有兩者的優點。

根據預設，即時資料表的分區到期時間為 30 天。如要瞭解如何修改這項設定，請參閱 BigQuery 說明文件中的「設定分割區到期時間」。

^{* 如要瞭解回填支援的詳細資訊，請參閱「升級至新的匯出基礎架構」。}

啟用匯出至「BigQuery」的功能

1. 前往 Firebase 控制台的「整合」頁面。

2. 在 BigQuery 資訊卡中，按一下「連結」。

3. 按照畫面上的指示啟用匯出至 BigQuery 的功能， 包括下列選項：

   • 如要進一步瞭解未受當機影響的使用者和未發生當機情形的工作階段，請啟用 Firebase 工作階段資料匯出功能。

   • 如要在 BigQuery 中近乎即時地存取 Crashlytics 資料和 Firebase 工作階段資料，請啟用串流匯出功能。

啟用匯出功能後會發生什麼情況？

• Firebase 會匯出連結至 BigQuery 的應用程式資料。

  • 設定時，專案中的所有應用程式預設都會連結至 BigQuery，但您可以在設定期間選擇「不」連結特定應用程式。

  • 您之後加進 Firebase 專案的應用程式，都會自動連結至 BigQuery。

  • 您隨時可以管理哪些應用程式可以匯出資料。

• Firebase 會將資料匯出至您在設定期間選取的資料集位置。

  • 這個位置會同時套用到 Crashlytics 資料集和 Firebase 工作階段資料集 (如果已啟用工作階段資料匯出功能)。

  • 這個位置僅適用於匯出至 BigQuery 的資料，不會影響儲存的資料位置，這些資料可用於 Firebase 控制台的 Crashlytics 資訊主頁或 Android Studio。

  • 資料集建立後，該資料集的位置就無法再變更，不過您可以將資料集複製到其他位置，或將資料集手動移動 (重新建立) 至其他位置。詳情請參閱「變更現有匯出作業的位置」。

• Firebase 會設定每日將批次資料同步至 BigQuery。

  • 連結至 BigQuery 後，初始批次資料匯出作業最多可能需要 48 小時。

  • 無論您在 BigQuery 中設定的排定匯出作業為何，系統每天都會執行一次每日同步作業。請注意，同步作業的時間和持續時間可能會變更，因此不建議根據匯出的特定時間安排下游作業或工作。

• Firebase 會將現有資料副本匯出至 BigQuery。

  • 針對每個連結的應用程式，匯出內容會包含一個批次資料表，內含每日同步處理的資料。

  • 您可以手動排定資料回填作業，為批次資料表回填過去 30 天的資料或啟用匯出至 BigQuery 的最新日期資料 (以較近的日期為準)。

  請注意，如果您在 2024 年 10 月中旬前啟用 Crashlytics 資料匯出功能，也可以回填啟用匯出功能前 30 天的資料。

• 如果您啟用串流匯出至 BigQuery，則適用下列規定。

  • 此外，每個已連結的應用程式都會有自己的即時資料表，其中包含持續更新的資料 (除了應用程式的批次資料表，用於每日批次匯出)。

  • 啟用串流後，最多可能需要 1 小時，資料才會開始串流。

  即時資料表未顯示資料嗎？

  1. 請確認您已從應用程式傳送至少兩個事件至 Crashlytics，並在傳送後等待幾分鐘。

  2. 確認 Firebase 專案採用即付即用 Blaze 定價方案。
     查看Firebase控制台左下角即可確認。

  3. 傳送兩個事件並等待幾分鐘後，如果即時表格仍未顯示資料，請按照下列步驟操作：

     1. 前往 Firebase 控制台的BigQuery 資訊卡。

     2. 停用再重新啟用串流匯出功能。

     3. 請確認服務帳戶service-PROJECT_NUMBER@gcp-sa-crashlytics.iam.gserviceaccount.com位於 Firebase 專案中，且具備「Firebase Crashlytics 服務代理人」角色。
        您可以在Google Cloud控制台的「IAM」頁面中檢查這項設定 (請務必選取「包含 Google 提供的角色授權」核取方塊)。

     4. 至少將兩個事件傳送至 Crashlytics，並等待幾分鐘。

  4. 如果即時資料表仍未顯示資料，請與 Firebase 支援團隊聯絡。

查詢範例

範例 1：使用 Firebase 工作階段資料計算未發生當機情形的指標

您在最新版本中大幅改版應用程式，解決重要使用者歷程中的當機問題。您收到許多使用者好評，但希望取得量化證據，證明應用程式比以往更穩定。

未發生當機情形的指標可協助您取得這項資訊。這些指標是重要的評估標準，有助於瞭解應用程式的整體健康狀態。您可以使用基本查詢，透過 Firebase 工作階段資料和 Crashlytics 事件計算這些指標。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

特定版本的未遇到當機情形的使用者：

SELECT
  TIMESTAMP_TRUNC(crashlytics.event_timestamp,DAY) AS event_date,
  (1 - (COUNT (DISTINCT installation_uuid) / COUNT (DISTINCT instance_id))) AS CFU
FROM
  `PROJECT_ID.firebase_sessions.PACKAGE_NAME_ANDROID` AS sessions
LEFT JOIN
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID` AS crashlytics
ON
  TIMESTAMP_TRUNC(_PARTITIONTIME,DAY) = TIMESTAMP_TRUNC(crashlytics.event_timestamp,DAY)
WHERE
  crashlytics.error_type="FATAL"
  AND crashlytics.application.display_version="APP_VERSION"
  AND sessions.application.display_version = "APP_VERSION"
GROUP BY
  event_date
ORDER BY
  event_date

過去一週 (過去 168 小時) 未發生當機情形的工作階段：

SELECT
  TIMESTAMP_TRUNC(crashlytics.event_timestamp,DAY) AS event_date,
  (1 - (COUNT (DISTINCT crashlytics.event_id) / COUNT (DISTINCT sessions.session_id))) AS CFS
FROM
  `PROJECT_ID.firebase_sessions.PACKAGE_NAME_ANDROID` AS sessions
LEFT JOIN
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID` AS crashlytics
ON
  TIMESTAMP_TRUNC(_PARTITIONTIME,DAY) = TIMESTAMP_TRUNC(crashlytics.event_timestamp,DAY)
WHERE
  crashlytics.error_type="FATAL" AND _PARTITIONTIME >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 168 HOUR)
  AND _PARTITIONTIME < CURRENT_TIMESTAMP()
GROUP BY
  event_date
ORDER BY
  event_date

範例 2：按天顯示的當機次數

在開發人員盡力修正各種錯誤後，您認為團隊終於可以推出新的相片分享應用程式。不過，您想先查看過去一個月內每天當機的次數，確認這段時間排除錯誤的確讓應用程式變得更穩定。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT
  COUNT(DISTINCT event_id) AS number_of_crashes,
  FORMAT_TIMESTAMP("%F", event_timestamp) AS date_of_crashes
FROM
 `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID`
GROUP BY
  date_of_crashes
ORDER BY
  date_of_crashes DESC
LIMIT 30;

範例 3：找出最常發生的當機問題

為了適當排定生產計畫的優先順序，您想找出應用程式中最常出現的 10 大當機問題，因此產生查詢，提供相關資料點。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT
  DISTINCT issue_id,
  COUNT(DISTINCT event_id) AS number_of_crashes,
  COUNT(DISTINCT installation_uuid) AS number_of_impacted_user,
  blame_frame.file,
  blame_frame.line
FROM
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID`
WHERE
  event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL 168 HOUR)
  AND event_timestamp < CURRENT_TIMESTAMP()
GROUP BY
  issue_id,
  blame_frame.file,
  blame_frame.line
ORDER BY
  number_of_crashes DESC
LIMIT 10;

範例 4：前 10 大當機裝置

秋天是換新手機的季節！貴公司知道這也代表新手機問題特別多的季節來臨，Android 更是如此。為了提早因應即將到來的相容性問題，您做了一個查詢，找出最近一週 (168 小時) 最常當機的 10 台裝置。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT
  device.model,
COUNT(DISTINCT event_id) AS number_of_crashes
FROM
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID`
WHERE
  event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 168 HOUR)
  AND event_timestamp < CURRENT_TIMESTAMP()
GROUP BY
  device.model
ORDER BY
  number_of_crashes DESC
LIMIT 10;

範例 5：依自訂鍵篩選

您是遊戲開發人員，想知道遊戲的哪個關卡最常當機。

為了協助追蹤該統計資料，您設定了名為 current_level 的自訂 Crashlytics 鍵，並在使用者每次到達新關卡時更新該鍵。

Crashlytics.sharedInstance().setIntValue(3, forKey: "current_level");

CrashlyticsKit setIntValue:3 forKey:@"current_level";

Crashlytics.setInt("current_level", 3);

透過匯出至 BigQuery 中的這個鍵，您可以撰寫查詢，回報與每次當機事件相關聯的 current_level 值分佈情況。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT
COUNT(DISTINCT event_id) AS num_of_crashes,
  value
FROM
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID`
UNNEST(custom_keys)
WHERE
  key = "current_level"
GROUP BY
  key,
  value
ORDER BY
  num_of_crashes DESC

範例 6：擷取 User-ID

您有一個處於搶先體驗階段的 Android 應用程式。大部分使用者都對該應用程式感到滿意，但有三位使用者則遇到不尋常的當機次數。為了釐清問題的真正原因，您撰寫查詢，使用這些使用者的 ID 來提取所有當機事件。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT *
FROM
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID`
WHERE
  user.id IN ("USER_ID_1", "USER_ID_2", "USER_ID_3")
ORDER BY
  user.id
 

範例 7：找出所有發生特定當機問題的使用者

您的團隊不慎將重大錯誤發布給一群 Beta 版測試人員。 您的團隊已使用上述「找出最常發生的當機問題」範例中的查詢，找出特定當機問題 ID。現在團隊想執行查詢，擷取受這個當機問題影響的應用程式使用者清單。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT user.id as user_id
FROM
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID`
WHERE
  issue_id = "ISSUE_ID"
  AND application.display_version = "APP_VERSION"
  AND user.id != ""
ORDER BY
  user.id;

範例 8：按國家/地區劃分，受當機問題影響的使用者人數

您的團隊在推出新版本時發現重大錯誤，您可以使用上述「找出最普遍的當機問題」範例中的查詢，找出特定當機問題 ID。現在，您的團隊想瞭解這項當機問題是否已擴散到世界各地。

如要編寫這項查詢，您的團隊需要執行下列操作：

1. 啟用將 Google Analytics 資料匯出至 BigQuery 的功能。 請參閱「將專案資料匯出至 BigQuery」。

2. 更新應用程式，將使用者 ID 傳遞至 Google Analytics SDK 和 Crashlytics SDK。

   Swift

   Crashlytics.sharedInstance().setUserIdentifier("123456789");
   Analytics.setUserID("123456789");
   

   Objective-C

   CrashlyticsKit setUserIdentifier:@"123456789";
   FIRAnalytics setUserID:@"12345678 9";
   

   Java

   Crashlytics.setUserIdentifier("123456789");
   mFirebaseAnalytics.setUserId("123456789");
   

3. 撰寫查詢，使用使用者 ID 欄位將 Google Analytics 資料集中的事件與 Crashlytics 資料集中的當機事件合併。

   以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

   SELECT DISTINCT c.issue_id, a.geo.country, COUNT(DISTINCT c.user.id) as num_users_impacted
   FROM `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID` c
   INNER JOIN  `PROJECT_ID.analytics_TABLE_NAME.events_*` a on c.user.id = a.user_id
   WHERE
     c.issue_id = "ISSUE_ID"
     AND a._TABLE_SUFFIX BETWEEN '20190101'
     AND '20200101'
   GROUP BY
     c.issue_id,
     a.geo.country,
     c.user.id

範例 9：今天目前為止的前 5 大問題

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT
  issue_id,
  COUNT(DISTINCT event_id) AS events
FROM
  `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID_REALTIME`
WHERE
  DATE(event_timestamp) = CURRENT_DATE()
GROUP BY
  issue_id
ORDER BY
  events DESC
LIMIT
  5;

範例 10：自「DATE」起 (含今天) 的前 5 大問題

您也可以使用縫合查詢，合併批次和即時資料表，將即時資訊新增至可靠的批次資料。由於 event_id 是主鍵，因此您可以使用 DISTINCT event_id，從這兩個資料表中移除任何常見的重複事件。

以下是 Android 應用程式的查詢範例。如果是 iOS 應用程式，請使用軟體包 ID 和 IOS (而非套件名稱和 ANDROID)。

SELECT
  issue_id,
  COUNT(DISTINCT event_id) AS events
FROM (
  SELECT
    issue_id,
    event_id,
    event_timestamp
  FROM
    `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID_REALTIME`
  UNION ALL
  SELECT
    issue_id,
    event_id,
    event_timestamp
  FROM
    `PROJECT_ID.firebase_crashlytics.PACKAGE_NAME_ANDROID`)
WHERE
  event_timestamp >= PARSE_TIMESTAMP("%Y_%m_%d", "YYYY_MM_DD")
GROUP BY
  issue_id
ORDER BY
  events DESC
LIMIT
  5;

使用 Looker Studio以視覺化方式呈現匯出的 Crashlytics 資料

Looker Studio 可將 BigQuery 中的 Crashlytics 資料集轉換為報表，方便您閱讀、分享及自訂。

如要進一步瞭解如何使用 Looker Studio，請參閱歡迎指南。

使用 Crashlytics 報表範本

Looker Studio提供 Crashlytics 範例報表，其中包含從匯出的 Crashlytics BigQuery結構定義中取得的一組完整維度和指標。如果您已啟用Crashlytics串流匯出功能BigQuery，即可在Looker Studio範本的「即時趨勢」頁面查看資料。您可以使用該範例做為範本，依據您自己應用程式上的原始當機資料，快速建立新的報表與視覺化效果：

1. 開啟「Crashlytics Looker Studio 資訊主頁範本」。

2. 按一下右上角的 [Use Template] (使用範本)。

3. 在「新資料來源」下拉式選單中，選取「建立新資料來源」。

4. 按一下「BigQuery」資訊卡上的「選取」。

5. 依序選取「我的專案」> PROJECT_ID >「firebase_crashlytics」> TABLE_NAME，選擇包含匯出 Crashlytics 資料的資料表。

   你隨時可以選取批次表格。如果啟用Crashlytics串流匯出至 BigQuery，則可改為選取即時資料表。

6. 在「Configuration」(設定) 底下，將「Crashlytics Template level」(範本等級) 設為「Default」(預設)。

7. 按一下 [Connect] (連結) 建立新的資料來源。

8. 按一下「加入報表」，即可返回 Crashlytics 範本。

9. 最後按一下「建立報表」，建立 Crashlytics Looker Studio 資訊主頁範本的副本。