Java-Anwendungen für Error Reporting instrumentieren

Mithilfe des Error Reporting-Pakets für Java können Sie Fehlerberichte von Java-Anwendungen an Error Reporting senden. Mit dem Error Reporting-Paket für Java können Sie Fehlergruppen für die folgenden Fälle erstellen:

• Ein Log-Bucket, der Ihre Protokolleinträge enthält, hat vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK).
• Der Log-Bucket erfüllt eine der folgenden Bedingungen:
  • Der Protokoll-Bucket wird im selben Projekt gespeichert, aus dem die Protokolleinträge stammen.
  • Die Logeinträge wurden an ein Projekt weitergeleitet und dann in einem zugehörigen Log-Bucket gespeichert.
• Sie möchten benutzerdefinierte Fehlerereignisse melden.

Error Reporting ist in einige Google Cloud-Dienste wie Cloud Functions, App Engine, Compute Engine und Google Kubernetes Engine eingebunden. In Error Reporting sehen Sie die in Cloud Logging protokollierten Fehler der auf diesen Diensten ausgeführten Anwendungen. Weitere Informationen finden Sie auf dieser Seite im Abschnitt In Google Cloud ausführen.

Sie können Fehlerdaten auch mithilfe von Logging an Error Reporting senden. Informationen zu den Datenformatierungsanforderungen finden Sie unter Fehlermeldungen in Logging formatieren.

Hinweise

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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

Clientbibliothek installieren

Mit dem Error Reporting-Paket für Java können Sie die von Java-Anwendungen gemeldeten Fehler im Blick behalten und abrufen. Dabei ist es in den meisten Fällen unerheblich, wo die Anwendungen ausgeführt werden.

Weitere Informationen zur Installation finden Sie in der Dokumentation des Error Reporting-Pakets für Java. Probleme können Sie über die Problemverfolgung melden.

Clientbibliothek konfigurieren

Das Verhalten des Error Reporting-Pakets für Java kann angepasst werden. Weitere Informationen finden Sie in der Java API-Referenzdokumentation.

Apps in Google Cloud ausführen

Wenn Sie mit projects.events.report Fehlergruppen erstellen möchten, benötigt Ihr Dienstkonto die Rolle Error Reporting Writer (roles/errorreporting.writer).

Einigen Google Cloud-Diensten wird dem entsprechenden Dienstkonto automatisch die Rolle „Autor für Fehlerberichte“ (roles/errorreporting.writer) zugewiesen. Bei einigen Diensten müssen Sie diese Rolle jedoch dem entsprechenden Dienstkonto zuweisen.

Cloud Run und Cloud Run-Funktionen

Das von Cloud Run verwendete Standarddienstkonto hat die Berechtigungen der Rolle Error Reporting-Autor (roles/errorreporting.writer).

Das Error Reporting-Paket für Java kann verwendet werden, ohne dass Anmeldeinformationen explizit angegeben werden müssen.

Cloud Run ist für die automatische Verwendung von Error Reporting konfiguriert. Unverarbeitete JavaScript-Ausnahmen werden in Logging angezeigt und von Error Reporting verarbeitet, ohne dass dafür das Error Reporting-Paket für Java angewendet werden muss.

Hinweis: Logeinträge werden automatisch ohne das Error Reporting-Paket für Java verarbeitet, wenn sie einen Stacktrace enthalten und entweder kein Logschweregrad oder zumindest der Logschweregrad ERROR angegeben ist.

Flexible App Engine-Umgebung

In der App Engine wird Ihrem Standarddienstkonto automatisch die Rolle Error Reporting-Autor (roles/errorreporting.writer) zugewiesen.

Das Error Reporting-Paket für Java kann verwendet werden, ohne dass Anmeldeinformationen explizit angegeben werden müssen.

Error Reporting wird für Anwendungen in flexiblen App Engine-Umgebungen automatisch aktiviert. Es ist keine zusätzliche Einrichtung erforderlich.

Hinweis: In stderr geschriebene Fehlerprotokolleinträge werden von Error Reporting automatisch verarbeitet, ohne dass dafür das Error Reporting-Paket für Java direkt angewendet werden muss.

@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

So verwenden Sie Error Reporting mit der Google Kubernetes Engine:

1. Dem Dienstkonto, das von Ihrem Container verwendet werden soll, muss die Rolle Error Reporting-Autor (roles/errorreporting.writer) zugewiesen sein.

   Sie können entweder das Compute Engine-Standarddienstkonto oder ein benutzerdefiniertes Dienstkonto verwenden.

   Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

2. Erstellen Sie Ihren Cluster und gewähren Sie ihm den Zugriffsbereich cloud-platform.

   Im folgenden Beispiel wird mit dem Befehl „create“ der cloud-platform-Zugriffsbereich und ein Dienstkonto angegeben:

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

Hinweis :Nachdem Sie einen Cluster erstellt haben, können Sie das zugehörige Dienstkonto nicht mehr ändern.

Compute Engine

So verwenden Sie Error Reporting mit Compute Engine-VM-Instanzen:

1. Dem Dienstkonto, das von Ihrer VM-Instanz verwendet werden soll, muss die Rolle Error Reporting-Autor (roles/errorreporting.writer) zugewiesen sein.

   Sie können entweder das Compute Engine-Standarddienstkonto oder ein benutzerdefiniertes Dienstkonto verwenden.

   Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

2. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf:

   Zu Seite VM-Instanzen

   Wenn Sie diese Seite über die Suchleiste finden, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Compute Engine lautet.

3. Wählen Sie die VM-Instanz aus, für die Sie den cloud-platform Zugriffsbereich erhalten möchten.

4. Klicken Sie auf Beenden und dann auf Bearbeiten.

5. Wählen Sie im Abschnitt Identität und API-Zugriff ein Dienstkonto mit der Rolle „Error Reporting-Autor“ (roles/errorreporting.writer) aus.

6. Wählen Sie im Bereich Zugriffsbereiche die Option Uneingeschränkten Zugriff auf alle Cloud APIs zulassen aus und speichern Sie die Änderungen.

7. Klicken Sie auf Starten/Fortsetzen.

Beispiel

Mit Cloud Logging Logback Appender oder dem Handler "java.util.logging" protokollierte Ausnahmen werden automatisch an die Error Reporting Console gemeldet.

Im folgenden Beispiel wird gezeigt, wie ein benutzerdefiniertes Fehlerereignis mit der Java-Clientbibliothek gemeldet wird:

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);
    }
  }
}

Wie Sie Fehlerstatistiken und Daten zu einzelnen Ereignissen abrufen und verwalten, erfahren Sie in der Java API-Referenzdokumentation.

Apps in einer lokalen Entwicklungsumgebung ausführen

Wenn Sie das Error Reporting-Paket für Java in einer lokalen Entwicklungsumgebung verwenden möchten, z. B. um die Bibliothek auf Ihrem eigenen Workstation auszuführen, müssen Sie Ihrem Error Reporting-Paket für Java die Standardanmeldedaten der lokalen Anwendung zur Verfügung stellen. Weitere Informationen finden Sie unter Bei Error Reporting authentifizieren.

Wenn Sie die Java Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

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.

   Note: If the gcloud CLI prints a warning that your account doesn't have the serviceusage.services.use permission, then some gcloud CLI commands and client libraries might not work. Ask an administrator to grant you the Service Usage Consumer IAM role (roles/serviceusage.serviceUsageConsumer), then run the following command:

   gcloud auth application-default set-quota-project PROJECT_ID

Weitere Informationen unter Set up authentication for a local development environment.

Die projects.events.report-Methode unterstützt auch API-Schlüssel. Wenn Sie API-Schlüssel für die Authentifizierung verwenden möchten, müssen Sie keine lokale Datei mit den Standardanmeldedaten für Anwendungen einrichten. Weitere Informationen unter Erstellen eines API-Schlüssels in der Dokumentation zur Google Cloud-Authentifizierung.

Fehlerberichte ansehen

Rufen Sie in der Google Cloud Console die Seite Fehlerberichte auf:

Error Reporting aufrufen

Sie können diese Seite auch über die Suchleiste finden.

Weitere Informationen finden Sie unter Fehler anzeigen.