Fehler in Logs formatieren

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

Sie können Fehlerereignisse an Ihr Google Cloud-Projekt melden, indem Sie die Cloud Logging API-Methode write oder die Error Reporting API-Methode report ausführen. Wenn Sie Fehlerereignisse über die Cloud Logging API melden, enthält der Anfragetext ein LogEntry-Objekt, das einen Stacktrace enthalten muss, oder ein ReportedErrorEvent-Objekt.

Hinweise

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

  • Wenn eine Authentifizierung auf Basis von API-Schlüsseln erforderlich ist, müssen Sie die Error Reporting API verwenden. Wenn Sie ein Fehlerereignis mithilfe 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, können für die Datenaufnahme in Cloud Logging Kosten anfallen. Unter Ausschlussfilter können Sie festlegen, welche Logs aufgenommen werden.

    Wenn Sie Fehlerereignisse mithilfe der Error Reporting API melden, gelten die übrigen Informationen in diesem Dokument nicht.

Formatanforderungen für LogEntry

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 ein Stacktrace ist, schreiben Sie das Fehlerereignis als einen der folgenden Typen:

  • Ein mehrzeiliges textPayload.

  • Ein jsonPayload mit dem Feld message, stack_trace oder exception.

    Sie können mehrere dieser Felder angeben. Wenn mehr als eines dieser Felder angegeben ist, lautet die Auswertungsreihenfolge: stack_trace, dann exception und dann message.

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

  • Eine jsonPayload, die kein message-, stack_trace- oder exception-Feld enthält, aber einen Stacktrace.

    Mit Error Reporting werden alle Felder in einem jsonPayload nach Stacktraces durchsucht. Wenn mehr als ein Stacktrace gefunden wird, wird ein Stacktrace ausgewählt. Der Auswahlalgorithmus sorgt für eine einheitliche Auswahl.

SMS protokollieren

Wenn Sie ein Fehlerereignis protokollieren möchten, bei dem es sich um eine Textnachricht handelt, verwenden Sie das folgende Format für 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 wären alle Pflichtfelder vorhanden. Daher wird in Error Reporting das Fehlerereignis erfasst.

Wenn Sie das Feld @type auf einen anderen Wert festlegen oder nicht konfigurieren, sucht Cloud Logging nach dem Feld mit der Bezeichnung serviceContext, um festzustellen, ob die Nutzlast ein ReportedErrorEvent-Objekt ist.

Sie müssen das Feld @type nicht festlegen, wenn die Felder message, stack_trace oder exception von jsonPayload einen Stacktrace enthalten. 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_job1
  • workflows.googleapis.com/Workflow
  • global1

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

Ein Fehlerereignis protokollieren, das eine Textnachricht ist

Das folgende Beispiel zeigt, wie Sie ein LogEntry-Objekt formatieren, wenn Sie ein Fehlerereignis protokollieren möchten, bei dem es sich um eine Textnachricht handelt. Verwenden Sie die folgende 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 setzen, der Error Reporting erzwingt, den Logeintrag zu gruppieren: Weitere Informationen finden Sie unter Textnachricht protokollieren.

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

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

Füllen Sie das Feld message unbedingt mit den Fehlerinformationen aus. Informationen zum Speichern eines Stacktrace im Feld message eines ReportedErrorEvent-Objekts finden Sie auf der Referenzseite für die Methode report.

Das folgende Beispiel zeigt, wie das Feld jsonPayload des LogEntry so festgelegt wird, 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 einer LogEntry verwenden, um die Fehlerdaten zu speichern. Der folgende Google Cloud CLI-Befehl führt beispielsweise zu einem Logeintrag mit der Wichtigkeitsstufe ERROR 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 nach 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)"
    ...
}