將 Firebase Crashlytics 資料匯出至 BigQuery

您可以將 Firebase Crashlytics 資料匯出至 BigQuery 進行進一步分析。BigQuery 可讓您使用 BigQuery SQL 分析資料、將資料匯出至其他雲端服務供應商，並透過 Google 數據分析製作資訊主頁和視覺化報表。

啟用匯出至 BigQuery

1. 在 Firebase 主控台中，前往「Integrations」頁面。

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

3. 按照畫面上的指示啟用匯出至 BigQuery 的功能。

   如果您想在 BigQuery 中近乎即時存取 Crashlytics 資料，建議您升級至串流匯出。

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

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

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

• 根據預設，您專案中的所有應用程式都會連結至 BigQuery，您之後才加進專案的應用程式也統統會自動與 BigQuery 連結。您可以管理要傳送資料的應用程式。

• Firebase 會設定每日同步處理資料至 BigQuery。

  • 連結專案後，您通常需要等到隔天同步作業，才能將第一組資料匯出至 BigQuery。

  • 無論您在 BigQuery 中設定了哪些排定匯出作業，每日同步作業都會每天執行一次。請注意，同步處理工作的時間和持續時間可能會變更，因此我們不建議根據匯出作業的特定時間安排後續作業或工作。

• Firebase 會將現有資料的副本匯出至 BigQuery。匯出資料的初始傳播作業最多可能需要 48 小時。

  • 對於每個已連結的應用程式，這個匯出作業會包含一張批次表格，其中包含每日同步作業的資料。

  • 您可以手動排定資料回填時間，讓���次表格回填至過去 30 天或您啟用匯出至 BigQuery 的最近日期 (以較晚者為準)。

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

• 如果您啟用 Crashlytics 串流匯出功能，將資料匯出至 BigQuery，則所有已連結的應用程式都會有一個即時資料表，其中包含持續更新的資料。

如要停用匯出至 BigQuery 的功能，請在 Firebase 控制台中取消連結專案。

匯出至 BigQuery 的資料有哪些？

Firebase Crashlytics 資料會匯出至名為 firebase_crashlytics 的 BigQuery 資料集。根據預設，系統會為專案中的每個應用程式在 Crashlytics 資料集中建立個別資料表。Firebase 會依據應用程式的 ID 來命名資料表，同時會將句號轉換為底線，並將平台名稱附加到結尾處。

舉例來說，套件名稱為 com.google.test 的 Android 應用程式資料會位於名為 com_google_test_ANDROID 的資料表中。這個批次表格每天會更新一次。如果您啟用 Crashlytics 串流匯出至 BigQuery，Crashlytics 資料也會即時串流至名為 com_google_test_ANDROID_REALTIME 的資料表。

表格中的每一列都代表應用程式中發生的事件，包括當機、非致命錯誤和 ANR。

Crashlytics 串流匯出至 BigQuery

您可以使用 BigQuery 串流，即時串流 Crashlytics 資料。您可以將這項功能用於任何需要即時資料的用途，例如在即時資訊主頁中呈現資訊、即時查看推出作業，或是監控會觸發快訊和自訂工作流程的應用程式問題。

啟用 Crashlytics 串流匯出至 BigQuery 後，除了批次表格，您還會有即時表格。以下是您應注意的兩個表格之間差異：

由於事件會在寫入前以持久性方式儲存，且最多可回填至表格 30 天*，因此批次表格非常適合用於長期分析及找出一段時間內的趨勢。當我們將資料寫入即時資料表時，會立即將資料寫入 BigQuery，因此非常適合用於即時資訊主頁和自訂快訊。這兩個資料表可以與拼接查詢結合，以便同時享有兩者的優點。

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

^{* 如要進一步瞭解回填支援功能，請參閱「升級至新的匯出基礎架構」一文。}

啟用 Crashlytics 串流匯出至 BigQuery

1. 在 Firebase 主控台中，前往「Integrations」頁面。

2. 在 BigQuery 資訊卡中，按一下「管理」。

3. 勾選「Include streaming」核取方塊。

這項操作會為所有已連結的應用程式啟用串流功能。

匯出的資料可做什麼用途？

匯出至 BigQuery 的資料包含原始當機資料，包括裝置類型、作業系統、例外狀況 (Android 應用程式) 或錯誤 (Apple 應用程式)，以及 Crashlytics 記錄和其他資料。

請在本頁後續部分查看匯出的 Crashlytics 資料和其資料表結構定義。

使用數據分析範本

如要在數據分析範本中啟用即時資料，請按照「使用數據分析視覺化匯出的 Crashlytics 資料」中的操作說明操作。

建立檢視表

您可以使用 BigQuery UI 將查詢轉換為檢視畫面。如需詳細操作說明，請參閱 BigQuery 說明文件中的「建立檢視畫面」。

執行查詢

下列範例示範您可以在 Crashlytics 資料上執行的查詢，以產生報表，將當機事件資料匯總至更容易理解的摘要中。由於這類報表不在 Firebase 控制台的 Crashlytics 資訊主頁中提供，因此可用於補充您對當機資料的分析和瞭解。

範例 1：當日的異常終止情形

在盡可能修正所有錯誤後，您認為團隊終於可以推出新的相片分享應用程式。在推出前，您想查看過去一個月內每天當機的次數，確認排除錯誤的確讓應用程式變得更穩定。

以下是 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;

範例 2：找出最常見的當機情形

為了適當排定生產計劃的優先順序，您需要找出應用程式中最常見的 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;

示例 3：前 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;

範例 4：依據自訂鍵篩選

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

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

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

CrashlyticsKit setIntValue:3 forKey:@"current_level";

Crashlytics.setInt("current_level", 3);

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

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
 

您的團隊不小心向一群 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;

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

您的團隊在推出新版本時偵測到重大錯誤。您可以使用上述「找出最常見的當機情形」範例中的查詢，找出特定的當機問題 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
   

範例 8：今天目前為止的 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;

範例 9：自「日期」起 (含當天) 的 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 >= "YYYY_MM_DD"
GROUP BY
  issue_id
ORDER BY
  events DESC
LIMIT
  5;

瞭解 BigQuery 中的 Crashlytics 結構定義

設定 Crashlytics 資料匯出至 BigQuery 後，Firebase 會匯出近期事件 (當機、非致命錯誤和 ANR)，包括連結前兩天出現的事件，並提供補充資料長達 30 天的選項。

從連結開始到您停用連結，Firebase 每天都會匯出 Crashlytics 事件。每次匯出後可能需要幾分鐘的時間，您才能在 BigQuery 中使用資料。

資料集

Crashlytics 會在 BigQuery 中為 Crashlytics 資料建立新的資料集。這個資料集會涵蓋整個專案，即使專案包含多個應用程式亦同。

表格

Crashlytics 會在資料集中為專案裡的每個應用程式建立資料表，除非您選擇停用該應用程式的匯出資料功能。Firebase 會依據應用程式的 ID 命名資料表，同時會將句號轉換為底線，並將平台名稱附加到結尾處。

舉例來說，套件名稱為 com.google.test 的 Android 應用程式資料會位於名為 com_google_test_ANDROID 的資料表中，而即時資料 (如果已啟用) 則會位於名為 com_google_test_ANDROID_REALTIME 的資料表中。

除了您在應用程式中定義的任何自訂 Crashlytics 鍵，資料表還包含一組標準 Crashlytics 資料。

資料列

每個在資料表中的資料列都代表應用程式遇到的某個錯誤。

欄

對於當機、非重大錯誤和 ANR 來說，資料表中的資料欄都完全相同。如果啟用 Crashlytics 串流匯出至 BigQuery，則即時資料表的資料欄會與批次資料表相同。請注意，資料列中可能會包含代表沒有堆疊追蹤記錄的事件的資料欄。

系統匯出的資料欄如下所示：

使用數據分析以圖表呈現匯出的 Crashlytics 資料

Google 數據分析可將您在 BigQuery 中的 Crashlytics 資料集轉換為易於閱讀、分享且可完全自訂的報表。

如要進一步瞭解如何使用數據分析，請參閱《數據分析快速入門指南》中的歡迎使用數據分析。

使用 Crashlytics 報表範本

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

1. 開啟 Crashlytics 數據分析資訊主頁範本。

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

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

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

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

   您隨時可以選取批次表格。如果啟用「將 Crashlytics 串流匯出至 BigQuery」功能，您可以改為選取即時資料表。

6. 在「Configuration」下方，將「Crashlytics Template level」設為「Default」。

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

8. 按一下「Add to Report」即可返回 Crashlytics 範本。

9. 最後按一下「Create Report」，建立 Crashlytics 數據分析資訊主頁範本的複本。

升級至新的匯出基礎架構

2024 年 10 月中��，Crashlytics 推出了新的基礎架構，可將 Crashlytics 資料匯出至 BigQuery。目前，升級至這項新基礎架構為選用功能。

這項新基礎架構支援美國境外的 Crashlytics 資料集位置。

• 如果您在 2024 年 10 月中旬之前啟用匯出功能，現在可以選擇將資料匯出位置變更為任何 BigQuery 支援的資料集位置。

• 如果您在 2024 年 10 月中旬或之後啟用匯出功能，在設定期間，您可以選取任何 BigQuery 支援的資料集位置。

新基礎架構的另一個差異之處，是無法從啟用匯出功能「之前」補充資料。(使用舊版基礎架構時，您最多可以回填到啟用日期前 30 天。)新基礎架構支援回填功能，可回填過去 30 天或您啟用匯出至 BigQuery 的最新日期 (以較晚者為準)。

升級前置條件

升級至新基礎架構前，請確認您符合下列先決條件：目前的批次 BigQuery 資料表的 ID 與已註冊 Firebase 應用程式設有的軟體包 ID 或套件名稱相符。

例如：

• 如果您有名為 com_yourcompany_yourproject_IOS 的 BigQuery 資料表，則應在 Firebase 專案中註冊 Firebase iOS+ 應用程式，並使用套件 ID com.yourcompany.yourproject。

• 如果您有名為 com_yourcompany_yourproject_ANDROID 的 BigQuery 資料表，則應在 Firebase 專案中註冊 Firebase Android 應用程式，套件名稱為 com.yourcompany.yourproject。

以下說明如何查看 Firebase 專案中註冊的所有 Firebase 應用程式：

1. 在 Firebase 主控台中，前往 settings「Project settings」。

2. 捲動至「您的應用程式」資訊卡，然後按一下所需的 Firebase 應用程式，即可查看應用程式資訊 (包括 ID)。

新的匯出基礎架構會根據已註冊 Firebase 應用程式設定的套件名稱或軟體包 ID，匯出每個應用程式的資料。為了避免中斷 BigQuery 工作流程，請務必確認目前的批次資料表已具有正確的名稱，以便新的基礎架構將所有新資料附加至現有資料表。如果批次資料表名稱「不」與已註冊的 Firebase 應用程式相符，但您仍想升級，請與 Firebase 支援團隊聯絡。

如何升級至新基礎架構

如果您已啟用匯出功能，只要在 Firebase 控制台中切換 Crashlytics 資料匯出功能，即可升級至新基礎架構。

詳細步驟如下：

1. 在 Firebase 主控台中，前往「Integrations」頁面。

2. 在 BigQuery 資訊卡中，按一下「管理」。

3. 關閉 Crashlytics 滑桿即可停用匯出功能。出現提示時，請確認要停止資料匯出作業。

4. 立即再次切換 Crashlytics 滑桿，重新啟用匯出功能。出現提示時，確認要匯出資料。

   您匯出至 BigQuery 的 Crashlytics 資料現在使用新的匯出基礎架構。