Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Logeintrag zum Melden von Fehlerereignissen formatieren

Sie können Cloud Logging-Logeinträge so formatieren, dass Error Reporting Ihre Anwendungsfehler automatisch erfasst und gruppiert. So können Sie Probleme in Ihren Diensten besser beobachten und diagnostizieren.

Wenn Sie Logeinträge mit Cloud Logging schreiben, muss das LogEntry-Objekt einen Stacktrace oder ein formatiertes ReportedErrorEvent-Objekt enthalten. In den folgenden Abschnitten erfahren Sie, wie Sie Textnutzlasten und JSON-Felder wie message, stack_trace und @type so formatieren, dass Error Reporting Ihre Fehlerereignisse korrekt parsen und gruppieren kann.

Hinweis

Folgen Sie der Einrichtungsanleitung für Ihre Sprache und Plattform.
Wenn Sie eine API-Schlüssel-basierte Authentifizierung benötigen, müssen Sie die Error Reporting API verwenden. Um ein Fehlerereignis mit der Error Reporting API zu melden, führen Sie die Methode report aus und formatieren Sie den Anfragetext der Methode als ReportedErrorEvent-Objekt.

Wenn Sie die Error Reporting API verwenden, werden Logeinträge mit korrekt formatierten Fehlermeldungen automatisch generiert und in Cloud Logginggeschrieben. Diese Logeinträge werden in ein Log geschrieben, dessen logName so formatiert ist:
```
projects/PROJECT_ID/clouderrorreporting.googleapis.com%2Freported_errors
```
Da Logeinträge durch Aufrufe von report generiert werden, können Kosten für die Aufnahme in Cloud Logging anfallen. Informationen dazu, welche Logeinträge aufgenommen werden, finden Sie unter Ausschlussfilter.

Wenn Sie Fehlerereignisse mit der Error Reporting API melden, gilt der Rest dieses Dokuments nicht.

`LogEntry`-Formatanforderungen

In diesem Abschnitt wird beschrieben, wie Sie ein LogEntry formatieren, damit Error Reporting das im Logeintrag enthaltene Fehlerereignis erfasst.

Stacktrace protokollieren

Wenn Sie ein Fehlerereignis protokollieren möchten, das ein Stacktrace ist, schreiben Sie das Fehlerereignis als einen der folgenden Typen:

Eine mehrzeilige textPayload.
Eine jsonPayload, die ein Feld message, stack_trace oder exception enthält.

Sie können mehrere dieser Felder angeben. Wenn mehrere dieser Felder angegeben werden, wird in der folgenden Reihenfolge ausgewertet: stack_trace, dann exception und dann message.

Wenn das Feld message ausgewertet wird und nicht leer ist, wird der Stacktrace nur erfasst, wenn das Feld einen Stacktrace in einem der unterstützten Formats der Programmiersprache enthält. Der Stacktrace wird von Error Reporting nicht erfasst, wenn ein nicht unterstütztes Format verwendet wird.

Wenn Ihr Fehlerereignis als ein ReportedErrorEvent-Objekt formatiert ist, kopieren Sie die Felder in die jsonPayload. Weitere Informationen und ein Beispiel finden Sie unter Fehler protokollieren, der als ReportedErrorEvent Objekt formatiert ist.
Eine jsonPayload, die kein Feld message, stack_trace oder exception enthält, aber einen Stacktrace.

Error Reporting durchsucht alle Felder in einer jsonPayload nach Stacktraces. Wenn mehrere Stacktraces gefunden werden, wird einer ausgewählt. Der Auswahlalgorithmus sorgt für eine konsistente Auswahl.

Textnachricht protokollieren

Wenn Sie ein Fehlerereignis protokollieren möchten, das eine Textnachricht ist, verwenden Sie das folgende Format für die jsonPayload:

    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "Text message"
    },

Wenn Sie das Feld @type auf den angegebenen Wert setzen, wertet Error Reporting den Logeintrag immer so aus, als ob alle erforderlichen Felder vorhanden sind. Dadurch erfasst Error Reporting das Fehlerereignis.

Wenn Sie das Feld @type auf einen anderen Wert setzen oder es nicht festlegen, sucht Cloud Logging nach einem Feld mit dem Label serviceContext, um zu ermitteln, ob die Nutzlast ein ReportedErrorEvent-Objekt ist.

Sie müssen das Feld @type nicht festlegen, wenn das Feld message, stack_trace oder exception der jsonPayload einen Stacktrace enthält. In diesen Fällen erfasst Error Reporting das Fehlerereignis automatisch.

Unterstützte überwachte Ressourcen

Legen Sie das Feld resource des Objekts LogEntry auf einen der folgenden unterstützten überwachten Ressourcentypen fest:

app_script_function
aws_ec2_instance
cloud_function
cloud_run_jobs
cloud_run_revision
consumed_api
container
dataflow_step
gae_app
gce_instance
k8s_container
k8s_pod
ml_job¹
workflows.googleapis.com/Workflow
global¹

¹textPayload wird nicht unterstützt

Beispiele

In diesem Abschnitt wird gezeigt, wie Sie dafür sorgen können, dass Error Reporting einen Logeintrag verarbeitet, wenn dieser eine Textnachricht oder einen Stacktrace enthält.

Fehlerereignis protokollieren, das eine Textnachricht ist

Wenn Sie ein Fehlerereignis protokollieren möchten, das eine Textnachricht ist, formatieren Sie das LogEntry-Objekt mit der folgenden JSON-Struktur für das Feld jsonPayload:

{...
  {
    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "A simple text message"
    },
    "logName": "projects/test-project/logs/reported-error",
    "resource": {
      "labels": {
        "project_id": "test-project"
      },
      "type": "global"
    },
    "severity": "ERROR",
    "timestamp": "2019-06-27T13:43:26.375834551Z"
  }
}

Wie im Beispiel gezeigt, müssen Sie das @type Feld auf den Wert setzen, der Error Reporting zwingt, den Logeintrag zu gruppieren. Weitere Informationen finden Sie unter Textnachricht protokollieren.

Wenn das Feld message einen Stacktrace enthält, wird der Logeintrag automatisch gruppiert. Sie müssen das Feld @type also nicht angeben.

Fehler protokollieren, der als `ReportedErrorEvent`-Objekt formatiert ist

Wenn Ihr Fehlerereignis in einem ReportedErrorEvent Objekt gespeichert ist, verwenden Sie die folgende JSON-Struktur für das Feld jsonPayload des LogEntry:

{
  "eventTime": string,
  "serviceContext": {
    "service": string,     // Required.
    "version": string
  },
  "message": string,       // Required. This field contains the main error content to report.
  "@type": string,         // Optional. For information about this field, see Log a text message.
  "context": {
    "httpRequest": {
      "method": string,
      "url": string,
      "userAgent": string,
      "referrer": string,
      "responseStatusCode": number,
      "remoteIp": string
    },
    "user": string,
    "reportLocation": {    // Required if no stack trace is provided.
      "filePath": string,
      "lineNumber": number,
      "functionName": string
    }
  }
}

Achten Sie darauf, dass Sie das Feld message mit den Fehlerinformationen füllen. Informationen zum Speichern eines Stacktraces im message Feld eines ReportedErrorEvent Objekts finden Sie auf der Referenzseite für die report Methode.

Das folgende Beispiel zeigt, wie Sie das Feld jsonPayload des LogEntry so festlegen, dass es als ReportedErrorEvent-Objekt formatiert wird. Da das Feld message einen Stacktrace enthält, wird das Fehlerereignis von Error Reporting gruppiert:

{...
   "jsonPayload": {
      "serviceContext": {
        "service": "frontend",
        "version": "bf6b5b09b9d3da92c7bf964ab1664fe751104517"
      },
      "message": "com.example.shop.Template$CartDiv retrieveCart: Error\njava.lang.IndexOutOfBoundsException: Index: 4, Size: 4\n\tat java.util.ArrayList.rangeCheck(ArrayList.java:635)\n\tat java.util.ArrayList.get(ArrayList.java:411)\n\tat com.example.shop.Cart.retrieve(Cart.java:76)\n\tat com.example.shop.Cart.generate(Cart.java:55)\n\tat com.example.shop.Template$CartDiv.retrieveCart(Template.java:113)\n\tat com.example.shop.Template.generate(Template.java:22)\n\tat com.example.shop.CartServlet.doGet(CartServlet.java:115)\n\tat javax.servlet.http.HttpServlet.service(HttpServlet.java:717)\n",
      "context": {
        "httpRequest": {
          "method": "GET",
          "url": "http://example.com/shop/cart",
          "responseStatusCode": 500
        },
        "user": "9f32f587135aa6774e78ed30fbaabcce3ec5528f"
      }
   },
   "logName": "projects/test-project/logs/reported-error",
   "resource": {
      "labels": {
        "project_id": "test-project"
      },
      "type": "global"
   },
   "severity": "ERROR",
   "timestamp": "2019-06-27T13:43:26.375834551Z"
}

Fehlerereignis mit dem Feld `textPayload` protokollieren

Sie können ein Fehlerereignis aufzeichnen, indem Sie das Feld textPayload eines LogEntry verwenden, um die Fehlermeldung zu speichern, z. B. einen Stacktrace. Der folgende Google Cloud CLI-Befehl führt beispielsweise zu einem Logeintrag, dessen Schweregrad ERROR ist und dessen Feld textPayload ein Fehlerereignis enthält:

gcloud logging write test-log --severity=ERROR --payload-type=text 'RuntimeException: Oops! Something bad happened.
at com.example.MyClass.method(MyClass.java:123)
at com.example.OtherClass.doStuff(Unknown Source)
at com.example.Sys.create(Native Method)'

Das Ergebnis des vorherigen Befehls ist ein Logeintrag, der von Error Reporting gruppiert wird:

{...
    logName: "projects/PROJECT_ID/logs/test-log"
    severity: "ERROR"
    textPayload: "RuntimeException: Oops! Something bad happened.
                  at com.example.MyClass.method(MyClass.java:123)
                  at com.example.OtherClass.doStuff(Unknown Source)
                  at com.example.Sys.create(Native Method)"
    ...
}

Logeintrag zum Melden von Fehlerereignissen formatieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.