為 PHP 應用程式進行檢測，以便回報錯誤

您可以使用 PHP 適用的 Error Reporting 程式庫，從 PHP 應用程式傳送錯誤報告至 Error Reporting。使用 PHP 適用的 Error Reporting 程式庫，針對下列情況建立錯誤群組：

  • 包含記錄項目的記錄值區具有客戶管理的加密金鑰 (CMEK)。
  • 記錄檔值區符合下列其中一個條件：
    • 記錄值區會儲存在記錄項目來源的專案中。
    • 記錄項目會轉送至專案，然後該專案會將這些記錄項目儲存在專案擁有的記錄值區中。
  • 您想回報自訂錯誤事件。

Error Reporting 已與部分 Google Cloud 服務整合，如 Cloud Functions、App Engine、Compute Engine 和 Google Kubernetes Engine。Error Reporting 能顯示在這些服務上執行的應用程式記錄到 Cloud Logging 的錯誤。詳情請參閱本頁面的「在 Google Cloud上執行」一節。

您也可以使用Logging，將錯誤資料傳送至 Error Reporting。如要瞭解資料格式要求，請參閱「在 Logging 中格式化錯誤訊息」。

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Error Reporting API .

    Enable the API

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Error Reporting API .

    Enable the API

    8.

    安裝用戶端程式庫

    PHP 適用的 Error Reporting 程式庫可讓您監控及查看在各處執行的 PHP 應用程式回報的錯誤。

    如要進一步瞭解安裝相關資訊，請參閱 PHP 適用的 Error Reporting 程式庫說明文件。您也可以使用問題追蹤工具回報問題。

    設定用戶端程式庫

    您可以自訂 PHP 適用的 Error Reporting 程式庫行為。如需可能設定選項的清單，請參閱程式庫設定說明。

    在 Google Cloud上執行應用程式

    如要使用 projects.events.report 建立錯誤群組，服務帳戶必須具備錯誤回報寫入者角色 (roles/errorreporting.writer)。

    部分 Google Cloud 服務會自動將「Error Reporting Writer」角色 (roles/errorreporting.writer) 授予適當的服務帳戶。不過，您必須為部分服務將這個角色授予適當的服務帳戶。

    Cloud Run 和 Cloud Run 函式

    Cloud Run 使用的預設服務帳戶具有Error Reporting 寫入者角色 (roles/errorreporting.writer) 的權限。

    不需要明確提供憑證，即可使用 PHP 適用的 Error Reporting 程式庫。

    Cloud Run 會設定為自動使用 Error Reporting。未處理的 JavaScript 例外狀況會出現在 Logging 之中並由 Error Reporting 處理，不需使用 PHP 適用的 Error Reporting 程式庫。

    App Engine 彈性環境

    App Engine 會自動將 Error Reporting 寫入者角色 (roles/errorreporting.writer) 授予預設服務帳戶。

    不需要明確提供憑證，即可使用 PHP 適用的 Error Reporting 程式庫。

    如要在 App Engine 彈性環境中啟用 Error Reporting，請按照下列步驟操作：

    1. 使用下列指令安裝必要的程式庫：

      $ composer require google/cloud-error-reporting

    2. 在 app.yaml 的 runtime_config 區段中新增下列程式碼行：

    enable_stackdriver_integration: true

    然後該程式庫會自動收集所有錯誤與未擷取到的例外狀況，並回報至 Error Reporting。如果您使用的是會安裝專屬例外狀況處理常式的網路架構，請參閱架構整合一節瞭解詳情。

    Google Kubernetes Engine

    如要搭配 Google Kubernetes Engine 使用錯誤回報功能，請按照下列步驟操作：

    1. 請確認要由容器使用的服務帳戶已獲准使用 Error Reporting 寫入者角色 (roles/errorreporting.writer)。

      您可以使用 Compute Engine 預設服務帳戶或自訂服務帳戶。

      如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

    2. 建立叢集，並授予叢集 cloud-platform 存取權範圍。

      舉例來說，下列建立指令會指定 cloud-platform 存取範圍和服務帳戶：

      gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform

    Compute Engine

    如要搭配 Compute Engine VM 執行個體使用錯誤回報功能，請執行下列操作：

    1. 請確認要由 VM 執行個體使用的服務帳戶已獲得 Error Reporting 寫入者角色 (roles/errorreporting.writer)。

      您可以使用 Compute Engine 預設服務帳戶或自訂服務帳戶。

      如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

    2. 前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面：

      前往「VM instances」(VM 執行個體) 頁面

      如果您是使用搜尋列尋找這個頁面，請選取子標題為「Compute Engine」的結果。

    3. 選取要接收 cloud-platform 存取範圍 的 VM 執行個體。

    4. 依序按一下「停止」和「編輯」。

    5. 在「Identity and API access」(身分及 API 存取權) 區段中，選取具有「Error Reporting Writer」(錯誤回報寫入者) 角色 (roles/errorreporting.writer) 的服務帳戶。

    6. 在「存取權範圍」部分，選取「允許所有 Cloud API 的完整存取權」，然後儲存變更。

    7. 按一下「開始/繼續」。

    範例

    1. 使用以下指令安裝雲端程式庫： 

    $ composer require google/cloud-error-reporting
     2. 將下列程式碼行新增至 php.ini，其中 WORKSPACE 是工作區根目錄的絕對路徑：
    auto_prepend_file='/WORKSPACE/vendor/google/cloud-error-reporting/src/prepend.php'

    此前置檔案會安裝例外狀況處理常式和錯誤處理常式，這兩個常式會自動將錯誤傳送至 Error Reporting。

    如果您使用的是 App Engine 彈性環境，請參閱本頁的「App Engine 彈性環境」一節。

    在本機開發環境中執行應用程式

    如要在本機開發環境中使用 PHP 適用的 Error Reporting 程式庫 (例如在您自己的工作站上執行程式庫)，您必須為 PHP 適用的 Error Reporting 程式庫提供本機應用程式預設憑證。詳情請參閱「向 Google 錯誤回報服務進行驗證」。

    如要在本機開發環境中使用本頁面上的 PHP 範例，請先安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  10. To initialize the gcloud CLI, run the following command: 

    gcloud init

  11. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    12. 詳情請參閱 Set up authentication for a local development environment。

    查看錯誤報告

    前往 Google Cloud 控制台的「Error Reporting」頁面：

    前往「錯誤回報」

    您也可以透過搜尋列找到這個頁面。

    詳情請參閱查看錯誤一文。

    架構整合

    部分網路架構會覆寫例外狀況處理常式。以下是使用 Laravel 和 Symfony 啟用 Error Reporting 的範例。對於其他架構，您可以使用 Google\Cloud\ErrorReporting\Bootstrap::exceptionHandler 做為例外狀況處理程序。

    Laravel

    編輯 app/Exceptions/Handler.php 檔案中的 report 函式，如下所示：

    public function report(Exception $exception)
{
    if (isset($_SERVER['GAE_SERVICE'])) {
        // Ensure Stackdriver is initialized and handle the exception
        Bootstrap::init();
        Bootstrap::exceptionHandler($exception);
    } else {
        parent::report($exception);
    }
}

    您也需要在檔案開頭新增一行 use 陳述式：

    use Google\Cloud\ErrorReporting\Bootstrap;

    Symfony

    建立名為 src/AppBundle/EventSubscriber/ExceptionSubscriber.php 的新檔案，並在其中加入下列內容：

    // src/AppBundle/EventSubscriber/ExceptionSubscriber.php
namespace AppBundle\EventSubscriber;

use Google\Cloud\ErrorReporting\Bootstrap;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class ExceptionSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        // return the subscribed events, their methods and priorities
        return [KernelEvents::EXCEPTION => [
            ['logException', 0]
        ]];
    }

    public function logException(ExceptionEvent $event)
    {
        $exception = $event->getThrowable();
        Bootstrap::exceptionHandler($exception);
    }
}