Error Reporting 用の Java アプリのインストルメント化

Java アプリケーションから Error Reporting にエラーイベントを送信するには、Java 用 Error Reporting パッケージを使用します。次の場合は、Java 用 Error Reporting パッケージを使用してエラーグループを作成します。

ログエントリを含むログバケットに、顧客管理の暗号鍵(CMEK)がある。
ログバケットが次のいずれかの条件を満たしている。
- ログバケットがログエントリの元のプロジェクトに保存されている。
- ログエントリがプロジェクトに転送され、そのプロジェクトがそれらのログエントリを、所有するログバケットに保存した。
カスタムエラーイベントを報告したい。

Error Reporting は、Cloud Run functions、App Engine、Compute Engine、Google Kubernetes Engine などの一部の Google Cloud サービスに統合されています。Error Reporting には、こうしたサービスで実行されるアプリケーションによって Cloud Logging に記録されたエラーイベントが表示されます。詳細については、このページの Google Cloudでの実行をご覧ください。

Logging を使用して、エラーイベントを Error Reporting に送信することもできます。データ形式の要件については、エラーイベントを報告するようにログエントリの形式を設定するをご覧ください。

始める前に

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API .

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API .

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

クライアントライブラリをインストールする

Java 用 Error Reporting パッケージを使用すると、ほぼすべての場所で動作している Java アプリケーションから報告されるエラーイベントをモニタリングして表示できます。

Maven を使用している場合は、次のものを pom.xml ファイルに追加します。BOM の詳細については、Google Cloud Platform ライブラリ BOM をご覧ください。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.78.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-errorreporting</artifactId>
  </dependency>
</dependencies>

Gradle を使用している場合は、次のものを依存関係に追加します。

implementation 'com.google.cloud:google-cloud-errorreporting:0.208.0-beta'

sbt を使用している場合は、次のものを依存関係に追加します。

libraryDependencies += "com.google.cloud" % "google-cloud-errorreporting" % "0.208.0-beta"

Visual Studio Code または IntelliJ を使用している場合は、次の IDE プラグインでプロジェクトにクライアントライブラリを追加できます。

プラグインでは、サービスアカウントのキー管理などの追加機能も提供されます。詳細は各プラグインのドキュメントをご覧ください。

インストールの詳細については、Java 用 Error Reporting パッケージのドキュメントをご覧ください。公開バグトラッカーを使用して問題を報告することもできます。

クライアントライブラリを設定する

Java 用 Error Reporting パッケージの動作をカスタマイズできます。Java API リファレンスドキュメントをご覧ください。

Google Cloudでアプリを実行する

projects.events.report を使用してエラーグループを作成するには、サービスアカウントに Error Reporting 書き込みロール（roles/errorreporting.writer）が必要です。

一部の Google Cloud サービスでは、Error Reporting 書き込みロール（roles/errorreporting.writer）が適切なサービスアカウントに自動的に付与されます。ただし、一部のサービスでは、このロールを適切なサービスアカウントに付与する必要があります。

Cloud Run と Cloud Run functions

Cloud Run で使用されるデフォルトのサービスアカウントには、Error Reporting 書き込みロール（roles/errorreporting.writer）の権限があります。

Java 用 Error Reporting パッケージは、明示的に認証情報を提示しなくても使用できます。

Cloud Run は、自動的に Error Reporting を使用するように構成されています。JavaScript の未処理の例外は、Logging に表示され、Java 用 Error Reporting パッケージを使用しなくても、Error Reporting によって処理されます。

App Engine フレキシブル環境

App Engine では、デフォルトのサービスアカウントに Error Reporting 書き込みロール（roles/errorreporting.writer）が自動的に付与されます。

Java 用 Error Reporting パッケージは、明示的に認証情報を提示しなくても使用できます。

App Engine のフレキシブル環境のアプリケーションでは、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

Google Kubernetes Engine で Error Reporting を使用するには、次の操作を行います。

コンテナが使用するサービスアカウントに、Error Reporting 書き込みロール（roles/errorreporting.writer）が付与されていることを確認します。

Compute Engine のデフォルトのサービスアカウントまたはカスタムサービスアカウントを使用できます。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。
クラスタを作成し、クラスタに cloud-platform アクセススコープを付与します。

たとえば、次の create コマンドは、cloud-platform アクセススコープとサービスアカウントを指定します。
```
gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform
```

Compute Engine

Compute Engine VM インスタンスで Error Reporting を使用するには、次の操作を行います。

VM インスタンスが使用するサービスアカウントに、Error Reporting 書き込みロール（roles/errorreporting.writer）が付与されていることを確認します。

Compute Engine のデフォルトのサービスアカウントまたはカスタムサービスアカウントを使用できます。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。
Google Cloud コンソールで [VM インスタンス] ページに移動します。
[VM インスタンス] に移動

検索バーを使用してこのページを検索する場合は、小見出しが [Compute Engine] である結果を選択します。
cloud-platform アクセススコープを適用する VM インスタンスを選択します。
[停止] をクリックし、[編集] をクリックします。
[ID と API へのアクセス] セクションで、Error Reporting 書き込みロール（roles/errorreporting.writer）を持つサービスアカウントを選択します。
[アクセススコープ] セクションで、[すべての Cloud API に完全アクセス権を許可] を選択し、変更を保存します。
[開始 / 再開] をクリックします。

例

Cloud Logging Logback Appender や java.util.logging Handler を使用して記録された例外は、Error Reporting Console に自動的に報告されます。

次のサンプルは、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 をインストールして初期化し、ユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定します。

Google Cloud CLI をインストールします。
外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。
ローカルシェルを使用している場合は、ユーザーアカウントのローカル認証情報を作成します。
```
gcloud auth application-default login
```
Cloud Shell を使用している場合は、この操作を行う必要はありません。
注: 使用しているアカウントに serviceusage.services.use 権限がないという警告が gcloud CLI で表示される場合は、一部の gcloud CLI コマンドとクライアントライブラリが動作しない可能性があります。管理者に Service Usage Consumer IAM ロール（roles/serviceusage.serviceUsageConsumer）を付与してもらってから、次のコマンドを実行してください。
```
gcloud auth application-default set-quota-project PROJECT_ID
```
認証エラーが返され、外部 ID プロバイダ（IdP）を使用している場合は、連携 ID を使用して gcloud CLI にログインしていることを確認します。

詳細については、ローカル開発環境の認証を設定するをご覧ください。

projects.events.report メソッドは API キーもサポートしています。認証に API キーを使用する場合、ローカルのアプリケーションのデフォルト認証情報ファイルを設定する必要はありません。詳細については、 Google Cloud 認証ドキュメントの API キーを作成するをご覧ください。

エラーグループを表示する

Google Cloud コンソールで [Error Reporting] ページに移動します。

Error Reporting に移動

このページは、検索バーを使用して見つけることもできます。

詳細については、エラーグループの表示とフィルタリングをご覧ください。

Error Reporting 用の Java アプリのインストルメント化 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

クライアント ライブラリをインストールする

クライアント ライブラリを設定する

Google Cloudでアプリを実行する

Cloud Run と Cloud Run functions

App Engine フレキシブル環境

Google Kubernetes Engine

Compute Engine

例

ローカル開発環境でアプリを実行する

エラーグループを表示する

Error Reporting 用の Java アプリのインストルメント化

クライアントライブラリをインストールする

クライアントライブラリを設定する