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 API-Schlüsselbasis 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 Kosten für die Cloud Logging-Aufnahme anfallen. Unter Ausschlussfilter können Sie festlegen, welche Logs aufgenommen werden.

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

Formatanforderungen für LogEntry

In diesem Abschnitt wird beschrieben, wie ein LogEntry formatiert wird, 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 in 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 Reihenfolge der Auswertung: 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.

  • Ein jsonPayload, der kein Feld message, stack_trace oder exception, aber einen Stacktrace enthält.

    Error Reporting durchsucht alle Felder in einem jsonPayload nach Stacktraces. Wenn mehr als ein Stacktrace gefunden wird, wird ein Stacktrace ausgewählt. Der Auswahlalgorithmus sorgt für eine konsistente 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 erfasst Error Reporting die Fehlerereignisse.

Wenn Sie das Feld @type auf einen anderen Wert festlegen oder nicht konfigurieren, sucht Cloud Logging nach dem Feld 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 für das Feld resource des Objekts LogEntry 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 Logeintrag eine Textnachricht oder einen Stacktrace enthält.

Fehlerereignis protokollieren, bei dem es sich um eine Textnachricht handelt

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 der Datei 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 dazu 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, sodass Sie das Feld @type nicht angeben müssen.

Es wird ein Fehler protokolliert, der als ReportedErrorEvent-Objekt formatiert ist

Wenn das Fehlerereignis in einem ReportedErrorEvent-Objekt gespeichert wird, 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 der LogEntry so festgelegt wird, dass es als ReportedErrorEvent-Objekt formatiert wird. Da das Feld message einen Stacktrace enthält, wird das Fehlerereignis nach 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"
}

Im Feld textPayload ein Fehlerereignis 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)"
    ...
}