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. Verwenden Sie das Error Reporting-Paket für Java zum Erstellen von Fehlergruppen in den folgenden Fällen:

• Der Log-Bucket hat vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK).
• Die Log-Buckets befinden sich nicht in der Region global.
• Sie möchten benutzerdefinierte Fehlerereignisse melden.

Error Reporting ist in einige Google Cloud-Dienste wie 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 unter 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. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   Zur Projektauswahl

3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

4. Error Reporting API aktivieren.

   Aktivieren Sie die API

5. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   Zur Projektauswahl

6. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

7. Error Reporting API aktivieren.

   Aktivieren Sie die API

Clientbibliothek installieren

Mit dem Error Reporting-Paket für Java können Sie die von Java-Anwendungen gemeldeten Fehler im Blick behalten und ansehen. Dabei ist es in den meisten Fällen unerheblich, wo sie 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.

Anwendungen in Google Cloud ausführen

Zum Erstellen von Fehlergruppen mit projects.events.report benötigt Ihr Dienstkonto die Rolle Error Reporting-Autor (roles/errorreporting.writer).

Einige Google Cloud-Dienste gewähren dem entsprechenden Dienstkonto automatisch die Rolle „Error Reporting-Autor“ (roles/errorreporting.writer). Für einige Dienste müssen Sie diese Rolle jedoch dem entsprechenden Dienstkonto zuweisen.

Flexible App Engine-Umgebung

Die App Engine weist Ihrem Standarddienstkonto automatisch die Rolle Error Reporting-Autor (roles/errorreporting.writer) zu.

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 Fehlerlogs 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 Google Kubernetes Engine:

1. Prüfen Sie, ob dem Dienstkonto, das von Ihrem Container verwendet werden soll, die Rolle „Error Reporting-Autor“ (roles/errorreporting.writer) gewährt wurde.

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

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

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

   Mit dem folgenden Befehl „create“ werden beispielsweise der Zugriffsbereich cloud-platform 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 dessen Dienstkonto nicht mehr ändern.

Compute Engine

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

1. Achten Sie darauf, dass dem von Ihrer VM-Instanz zu verwendenden Dienstkonto die Rolle Error Reporting-Autor (roles/errorreporting.writer) gewährt wurde.

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

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

2. Wählen Sie im Navigationsbereich der Google Cloud Console Compute Engine und dann VM-Instanzen aus:

   Zu Seite VM-Instanzen

3. Wählen Sie die VM-Instanz aus, die den Zugriffsbereich cloud-platform erhalten soll.

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 Abschnitt Zugriffsbereiche die Option Uneingeschränkten Zugriff auf alle Cloud APIs zulassen aus und speichern Sie dann die Änderungen.

7. Klicken Sie auf Starten/Fortsetzen.

Beispiel

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

Im folgenden Beispiel wird gezeigt, wie mit der Java-Clientbibliothek ein benutzerdefiniertes Fehlerereignis 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.

Anwendungen in einer lokalen Entwicklungsumgebung ausführen

Wenn Sie das Error Reporting-Paket für Java in einer lokalen Entwicklungsumgebung verwenden möchten, beispielsweise zum Ausführen der Bibliothek auf Ihrer eigenen Workstation, müssen Sie dem Error Reporting-Paket für Java die lokalen Standardanmeldedaten für Anwendungen bereitstellen. Weitere Informationen finden Sie unter Bei Error Reporting authentifizieren.

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

1. Installieren Sie die Google Cloud CLI.

2. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:

   gcloud init

3. Erstellen Sie lokale Anmeldedaten zur Authentifizierung für Ihr Google-Konto:

   gcloud auth application-default login

   Hinweis: Wenn die gcloud CLI eine Warnung ausgibt, dass Ihr Konto nicht die Berechtigung serviceusage.services.use hat, funktionieren einige gcloud CLI-Befehle und Clientbibliotheken möglicherweise nicht. Bitten Sie einen Administrator, Ihnen die IAM-Rolle "Service Usage-Nutzer" (roles/serviceusage.serviceUsageConsumer) zuzuweisen, und führen Sie dann den folgenden Befehl aus:

   gcloud auth application-default set-quota-project PROJECT_ID

Weitere Informationen: Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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: Erstellen eines API-Schlüssels in der Dokumentation zur Google Cloud-Authentifizierung.

Fehlerberichte ansehen

Wählen Sie im Navigationsbereich der Google Cloud Console Error Reporting und dann Ihr Google Cloud-Projekt aus:

Zu Error Reporting

Weitere Informationen finden Sie unter Fehler anzeigen.