Fehler in Logs formatieren

In diesem Dokument wird beschrieben, wie Sie den Logeintrag formatieren, wenn Sie mit Cloud Logging Fehlerereignisse melden möchten.

Sie können Fehlerereignisse in Ihrem Google Cloud-Projekt melden, indem Sie die Cloud Logging API-Methode write oder die Error Reporting API-Methode report ausführen. Wenn Sie Fehlerereignisse mit der Cloud Logging API melden, enthält der Anfragekörper ein LogEntry-Objekt mit einem Stack-Trace oder ein ReportedErrorEvent-Objekt.

Hinweise

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

  • Wenn Sie eine API-Schlüssel-Authentifizierung benötigen, müssen Sie die Error Reporting API verwenden. 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 Protokoll geschrieben, dessen logName folgendermaßen formatiert ist:

    projects/PROJECT_ID/clouderrorreporting.googleapis.com%2Freported_errors

    Da Logeinträge durch Aufrufe von report generiert werden, können Datenaufnahmekosten in Cloud Logging anfallen. Informationen dazu, welche Logs 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 einen LogEntry so formatieren, dass Error Reporting das im Logeintrag enthaltene Fehlerereignis erfasst.

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:

  • Eine mehrzeilige textPayload.

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

    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 Nachrichtenfeld ausgewertet wird und nicht leer ist, wird der Stack-Trace nur erfasst, wenn das Feld einen Stack-Trace in einem der unterstützten Programmiersprachenformate enthält. Der Stack-Trace wird von Error Reporting nicht erfasst, wenn ein nicht unterstütztes Format verwendet wird.

    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.

    Bei der Fehlerbehebung werden alle Felder in einer jsonPayload nach Stack-Traces durchsucht. Wenn mehr als ein Stack-Trace gefunden wird, wird einer ausgewählt. Der Auswahlalgorithmus sorgt für eine einheitliche Auswahl.

SMS protokollieren

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

    "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 wird das Fehlerereignis von Error Reporting erfasst.

Wenn Sie das Feld @type auf einen anderen Wert setzen oder leer lassen, sucht Cloud Logging nach dem Feld serviceContext, um zu ermitteln, ob es sich bei der Nutzlast um ein ReportedErrorEvent-Objekt handelt.

Sie müssen das Feld @type nicht festlegen, wenn die Felder message, stack_trace oder exception der jsonPayload einen Stack-Trace 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 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_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 Form einer Textnachricht protokollieren

Das folgende Beispiel zeigt, wie Sie ein LogEntry-Objekt formatieren, wenn Sie ein Fehlerereignis protokollieren möchten, das eine Textnachricht ist. Verwenden Sie dazu die folgende JSON-Struktur für das Feld jsonPayload des 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 Stack-Trace enthält, wird der Logeintrag automatisch gruppiert. Sie müssen also das Feld @type nicht angeben.

Fehler protokollieren, der als ReportedErrorEvent-Objekt formatiert ist

Wenn das 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
    }
  }
}

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 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

Sie können ein Fehlerereignis erfassen, indem Sie die Fehlerdaten im Feld textPayload eines LogEntry speichern. Der folgende Google Cloud CLI-Befehl führt beispielsweise zu einem Logeintrag mit der Schwerestufe ERROR und dem Feld textPayload, das 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 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)"
    ...
}