为 Java 应用插桩以使用 Error Reporting

您可以使用 Java 版 Error Reporting 软件包，从 Java 应用向 Error Reporting 发送错误报告。您可以使用 Java 版 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. 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

安装客户端库

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

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

配置客户端库

您可以自定义 Java 版 Error Reporting 程序包的行为。请参阅 Java API 参考文档。

在 Google Cloud 上运行应用

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

某些 Google Cloud 服务会自动向相应的服务账号授予“错误报告写入器”角色 (roles/errorreporting.writer)。不过，对于某些服务，您必须向相应的服务账号授予此角色。

Cloud Run 和 Cloud Run functions

Cloud Run 使用的默认服务账号具有 Error Reporting Writer 角色 (roles/errorreporting.writer) 的权限。

无需明确提供凭据即可使用 Java 版 Error Reporting 软件包。

Cloud Run 已配置为自动使用 Error Reporting。未处理的 JavaScript 异常将在 Logging 中显示，并且会由 Error Reporting 进行处理，而无需使用 Java 版 Error Reporting 软件包。

App Engine 柔性环境

App Engine 会自动向您的默认服务账号授予 Error Reporting Writer 角色 (roles/errorreporting.writer)。

无需明确提供凭据即可使用 Java 版 Error Reporting 软件包。

@WebServlet(name = "Error reporting", value = "/error")
public class ErrorReportingExample extends HttpServlet {

  private Logger logger = Logger.getLogger(ErrorReportingExample.class.getName());

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws IOException, ServletException {

    // errors logged to stderr / Cloud logging with exceptions are automatically reported.
    logger.log(Level.SEVERE, "exception using log framework", new IllegalArgumentException());

    // use the error-reporting client library only if you require logging custom error events.
    logCustomErrorEvent();

    // runtime exceptions are also automatically reported.
    throw new RuntimeException("this is a runtime exception");
  }

  private void logCustomErrorEvent() {
    try (ReportErrorsServiceClient reportErrorsServiceClient = ReportErrorsServiceClient.create()) {
      // Custom error events require an error reporting location as well.
      ErrorContext errorContext =
          ErrorContext.newBuilder()
              .setReportLocation(
                  SourceLocation.newBuilder()
                      .setFilePath("Test.java")
                      .setLineNumber(10)
                      .setFunctionName("myMethod")
                      .build())
              .build();
      // Report a custom error event
      ReportedErrorEvent customErrorEvent =
          ReportedErrorEvent.getDefaultInstance()
              .toBuilder()
              .setMessage("custom error event")
              .setContext(errorContext)
              .build();

      // default project id
      ProjectName projectName = ProjectName.of(ServiceOptions.getDefaultProjectId());
      reportErrorsServiceClient.reportErrorEvent(projectName, customErrorEvent);
    } catch (Exception e) {
      logger.log(Level.SEVERE, "Exception encountered logging custom event", e);
    }
  }
}

Google Kubernetes Engine

如需将 Error Reporting 与 Google Kubernetes Engine 搭配使用，请执行以下操作：

1. 确保为容器使用的服务账号已被授予 Error Reporting Writer 角色 (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

如需将 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. 点击启动/恢复。

示例

使用 Cloud Logging Logback Appender 或 java.util.logging Handler 记录的异常会自动报告给 Error Reporting 控制台。

以下示例演示了如何使用 Java 客户端库报告自定义错误事件：

import com.google.cloud.ServiceOptions;
import com.google.devtools.clouderrorreporting.v1beta1.ProjectName;
import com.google.devtools.clouderrorreporting.v1beta1.ReportErrorsServiceClient;
import com.google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.StringWriter;

/**
 * Snippet demonstrates using the Error Reporting API to report an exception.
 * <p>
 * When the workload runs on App Engine, GKE, Cloud Functions or another managed environment,
 * printing the exception's stack trace to stderr will automatically report the error
 * to Error Reporting.
 */
public class QuickStart {

  static String projectId;

  public static void main(String[] args) throws Exception {
    // Set your Google Cloud Platform project ID via environment or explicitly
    projectId = ServiceOptions.getDefaultProjectId();
    if (args.length > 0) {
      projectId = args[0];
    } else {
      String value = System.getenv("GOOGLE_CLOUD_PROJECT");
      if (value != null && value.isEmpty()) {
        projectId = value;
      }
    }

    try {
      throw new Exception("Something went wrong");
    } catch (Exception ex) {
      reportError(ex);
    }
  }

  /**
   * Sends formatted error report to Google Cloud including the error context.
   *
   * @param ex Exception containing the error and the context.
   * @throws IOException if fails to communicate with Google Cloud
   */
  private static void reportError(Exception ex) throws IOException {
    try (ReportErrorsServiceClient serviceClient = ReportErrorsServiceClient.create()) {
      StringWriter sw = new StringWriter();
      PrintWriter pw = new PrintWriter(sw);
      ex.printStackTrace(pw);

      ReportedErrorEvent errorEvent = ReportedErrorEvent.getDefaultInstance()
          .toBuilder()
          .setMessage(sw.toString())
          .build();
      // If you need to report an error asynchronously, use reportErrorEventCallable()
      // method
      serviceClient.reportErrorEvent(ProjectName.of(projectId), errorEvent);
    }
  }
}

要了解如何检索和管理错误统计信息以及各个事件的数据，请查看 Java API 参考文档。

在本地开发环境中运行应用

如需在本地开发环境中使用 Java 版 Error Reporting 软件包（例如在您自己的工作站上运行该库），您必须为 Java 版 Error Reporting 软件包提供本地应用默认凭据。如需了解详情，请参阅对 Error Reporting 进行身份验证。

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

1. Install the Google Cloud CLI.

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

   gcloud init

3. 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.

如需了解详情，请参阅 Set up authentication for a local development environment。

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

查看错误报告

在 Google Cloud 控制台中，转到 Error Reporting 页面：

前往 Error Reporting

您也可以使用搜索栏查找此页面。

如需了解详情，请参阅查看错误。