Fehler in Logs formatieren

In diesem Dokument wird erläutert, wie Sie den Logeintrag formatieren, wenn Sie ihn verwenden möchten. Cloud Logging zum Melden von Fehlerereignissen.

Sie können Fehlerereignisse an Ihr Google Cloud-Projekt melden, indem Sie Ausführen der Cloud Logging API-Methode write oder der Error Reporting API-Methode, report Wenn Sie Fehlerereignisse mit der Cloud Logging API melden, enthält der Anfragetext ein LogEntry-Objekt mit einem Stack-Trace oder ein ReportedErrorEvent-Objekt.

Hinweise

  • Folgen Sie der Einrichtungsanleitung für Ihrer Sprache und Plattform.

  • Wenn Sie eine API-Schlüssel-basierte Authentifizierung benötigen, müssen Sie den Error Reporting API. Wenn Sie ein Fehlerereignis mit der Error Reporting API melden möchten, 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 Logging geschrieben. 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, entstehen möglicherweise Aufnahmekosten für Cloud Logging. Informationen dazu, welche Protokolle 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 so formatieren, dass es In Error Reporting wird das auftretende Fehlerereignis erfasst. im Logeintrag ein.

Stacktrace protokollieren

Wenn Sie ein Fehlerereignis protokollieren möchten, das einen Stacktrace enthält, müssen Sie das Ereignis als einen der folgenden Typen schreiben:

  • Ein mehrzeiliges textPayload-Element.

  • Ein jsonPayload, das message, stack_trace oder exception enthält ein.

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

    Wenn das Fehlerereignis als ReportedErrorEvent-Objekt formatiert ist, kopieren Sie die Felder in das jsonPayload. Weitere Informationen und ein Beispiel finden Sie unter Fehler protokollieren, der als ReportedErrorEvent-Objekt formatiert ist.

  • Ein jsonPayload, das kein Feld message, stack_trace oder exception enthält, aber einen Stack-Trace.

    Error Reporting durchsucht alle Felder einer jsonPayload nach Stacktraces. Wenn mehr als ein Stack-Trace gefunden wird, wird einer ausgewählt. Der Auswahlalgorithmus sorgt für eine einheitliche Auswahl.

SMS protokollieren

Um ein Fehlerereignis in Form einer Textnachricht zu protokollieren, 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 festlegen, wertet Error Reporting den Logeintrag immer so aus, als ob alle erforderlichen Felder vorhanden sind. Daher In Error Reporting wird das Fehlerereignis erfasst.

Wenn Sie das Feld @type auf einen anderen Wert setzen oder es nicht konfigurieren, dann Cloud Logging nach dem Feld serviceContext, um zu ermitteln, ob die Nutzlast Ein ReportedErrorEvent-Objekt.

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

Unterstützte überwachte Ressourcen

Legen Sie das Feld resource des Objekts LogEntry fest. auf eines der folgenden unterstützten überwachte Ressourcentypen:

  • 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_job1
  • workflows.googleapis.com/Workflow
  • global1

1 textPayload wird nicht unterstützt

Beispiele

In diesem Abschnitt erfahren Sie, wie Sie dafür sorgen können, dass ein Logeintrag von der Fehlermeldung verarbeitet wird, wenn er eine Textnachricht oder einen Stack-Trace enthält.

Fehlerereignis in Textnachricht protokollieren

Das folgende Beispiel zeigt, wie ein LogEntry-Objekt formatiert wird, wenn Sie ein Fehlerereignis protokollieren möchten, bei dem es sich um eine Textnachricht handelt, verwenden Sie JSON-Struktur für das Feld jsonPayload von LogEntry:

{...
  {
    "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 das Beispiel zeigt, müssen Sie das Feld @type auf den Wert festlegen, der die Fehlermeldung dazu zwingt, den Logeintrag zu gruppieren: Weitere Informationen finden Sie unter SMS protokollieren.

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

Fehler protokollieren, der als ReportedErrorEvent-Objekt formatiert ist

Wenn das Fehlerereignis in einem ReportedErrorEvent gespeichert wird -Objekt enthält, verwenden Sie die folgende JSON-Struktur für das Feld jsonPayload von 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
    }
  }
}

Geben Sie die Fehlerinformationen in das Feld message ein. Informationen zum Speichern eines Stack-Traces im Feld message eines ReportedErrorEvent-Objekts finden Sie auf der Referenzseite der Methode report.

Im folgenden Beispiel wird gezeigt, wie das Feld jsonPayload des Elements LogEntry so formatiert wird, dass es als ReportedErrorEvent-Objekt angezeigt 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"
}

Fehlerereignisse mit dem Feld textPayload erfassen

Mit dem Feld textPayload einer LogEntry können Sie ein Fehlerereignis erfassen. um die Fehlerdaten zu speichern. Beispiel: führt der folgende Google Cloud CLI-Befehl zu einem Logeintrag, Schweregrad ist ERROR und dessen Feld textPayload enthält Fehlerereignis:

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 nach Fehlermeldungen gruppiert ist:

{...
    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)"
    ...
}