对用于 Error Reporting 的 PHP 应用插桩

启用库

您可以使用 PHP 版 Error Reporting 库，从 PHP 应用向 Error Reporting 发送错误报告。在以下情况下使用 PHP 版 Error Reporting 库创建错误组：

• 您的日志存储桶具有客户管理的加密密钥 (CMEK)。
• 您的日志存储分区不在 global 区域。
• 您想要报告自定义错误事件。

Error Reporting 已与某些 Google Cloud 服务集成，例如 App Engine、Compute Engine 和 Google Kubernetes Engine。Error Reporting 可显示在这些服务上运行的应用记录到 Cloud Logging 中的错误。如需了解详情，请转到本页面上的在 Google Cloud 上运行。

您还可以使用 Logging 将错误数据发送到 Error Reporting。如需了解数据格式设置要求，请参阅设置 Logging 中的错误消息格式。

准备工作

1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

2. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

3. 确保您的 Google Cloud 项目已启用结算功能。

4. 启用 Error Reporting API 。

   启用 API

5. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

6. 确保您的 Google Cloud 项目已启用结算功能。

7. 启用 Error Reporting API 。

   启用 API

安装客户端库

借助 PHP 版 Error Reporting 库，您可以监控和查看几乎在任何位置运行的 PHP 应用所报告的错误。

如需详细了解如何安装，请参阅 PHP 版 Error Reporting 库的文档。您还可以使用问题跟踪器来报告问题。

配置客户端库

您可以自定义 PHP 版 Error Reporting 库的行为。如需查看可能的配置选项的列表，请参阅库的配置。

在 Google Cloud 上运行应用

如需使用 projects.events.report 创建错误组，您的服务帐号需要具备 Error Reporting Writer 角色 (roles/errorreporting.writer)。

某些 Google Cloud 服务会自动将 Error Reporting Writer 角色 (roles/errorreporting.writer) 授予相应的服务帐号。但是，您必须将此角色授予某些服务的相应服务帐号。

App Engine 柔性环境

App Engine 会自动为您的默认服务帐号授予 Error Reporting Writer 角色 (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

要将 Error Reporting 与 Google Kubernetes Engine 配合使用，请执行以下操作：

1. 请确保容器要使用的服务帐号已被授予 Error Reporting Writer 角色 (roles/errorreporting.writer)。

   您可以使用 Compute Engine 默认服务帐号或自定义服务帐号。

   如需了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

2. 创建集群并向集群授予 cloud-platform 访问权限范围。

   例如，以下 create 命令指定了 cloud-platform 访问权限范围和一个服务帐号：

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

注意 ：创建集群后，将无法更改其服务帐号。

Compute Engine

如需将 Error Reporting 与 Compute Engine 虚拟机实例搭配使用，请执行以下操作：

1. 请确保已向虚拟机实例要使用的服务帐号授予 Error Reporting Writer 角色 (roles/errorreporting.writer)。

   您可以使用 Compute Engine 默认服务帐号或自定义服务帐号。

   如需了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

2. 在 Google Cloud 控制台的导航面板中，选择 Compute Engine，然后选择虚拟机实例：

   前往虚拟机实例

3. 选择要接收 cloud-platform 访问权限范围的虚拟机实例。

4. 依次点击停止和修改。

5. 在身份和 API 访问权限部分，选择具有 Error Reporting Writer 角色 (roles/errorreporting.writer) 的服务帐号。

6. 在访问权限范围部分中，选择允许所有 Cloud API 的全面访问权限，然后保存更改。

7. 点击启动/恢复。

示例

1. 使用以下命令安装 Cloud 库：

$ 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 库提供本地应用默认凭据。如需了解详情，请参阅向 Error Reporting 进行身份验证。

如需从本地开发环境使用本页面上的 PHP 示例，请安装并初始化 gcloud CLI，然后使用用户凭据设置应用默认凭据。

1. 安装 Google Cloud CLI。

2. 如需初始化 gcloud CLI，请运行以下命令：

   gcloud init

3. 为您的 Google 账号创建本地身份验证凭据：

   gcloud auth application-default login

   注意：如果 gcloud CLI 输出警告，提示您的账号没有 serviceusage.services.use 权限，则某些 gcloud CLI 命令和客户端库可能无法正常运行。请让管理员授予您 Service Usage Consumer IAM 角色 (roles/serviceusage.serviceUsageConsumer)，然后运行以下命令：

   gcloud auth application-default set-quota-project PROJECT_ID

如需了解详情，请参阅 为本地开发环境设置身份验证。

projects.events.report 方法也支持 API 密钥。 如果要使用 API 密钥进行身份验证，则无需设置本地应用默认凭据文件。 如需了解详情，请参阅 在 Google Cloud 身份验证文档中创建 API 密钥。

查看错误报告

在 Google Cloud 控制台的导航面板中，选择 Error Reporting，然后选择您的 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);
    }
}