Fehler in Logs formatieren

Auf dieser Seite wird das Logeintragsformat erläutert, das für die Verwendung von Cloud Logging zum Melden von Fehlerereignissen erforderlich ist.

Hinweis

Wenn Sie die Error Reporting API verwenden, können Sie Fehlerereignisse aus Ihrer Anwendung melden, indem Sie sie in ReportedErrorEvent schreiben. Dadurch werden Logeinträge mit korrekt formatierten Fehlermeldungen in Cloud Logging generiert. Der resultierende logName ist so formatiert:

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

Durch Verwendung dieser Methode können Datenaufnahmekosten in Cloud Logging entstehen. Hinweise zur Kontrolle dieser Kosten finden Sie unter Log-Ausschlüsse.

Wenn Sie Cloud Logging zum Melden von Fehlerereignissen verwenden möchten, lesen Sie die folgenden Abschnitte.

Formatierungsanforderungen

Logeinträge in Cloud Logging, die Stacktraces oder Ausnahmen enthalten oder das Format ReportedErrorEvent haben, generieren Fehler in Error Reporting.

Fehlerdaten sollten im payload-Union-Feld von LogEntry als einer der folgenden Typen protokolliert werden:

  • Eine mehrzeilige textPayload
  • Das message-Feld von jsonPayload

Sie müssen außerdem der Einrichtungsanleitung für Ihre Sprache und Plattform folgen. Beim Logging der Fehlerdaten von App Engine, Compute Engine und Google Kubernetes Engine besteht die einzige Formatierungsanforderung darin, dass der Logeintrag die vollständige Ausnahmenachricht und den Stacktrace enthält.

Informationen zum Formatieren der Ausnahmenachricht und des Stacktrace finden Sie im Abschnitt ReportedErrorEvent auf der report-Referenzseite für Error Reporting.

@type angeben

Wenn der Logeintrag den @type von type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent enthält, wertet Error Reporting den Logeintrag so aus, als ob alle erforderlichen Felder vorhanden sind, und erfasst das Fehlerereignis.

JSON-Darstellung

Beim Senden von Fehlerdaten mit Cloud Logging muss das angegebene ReportedErrorEvent folgende JSON-Struktur haben:

    {
      "eventTime": string,
      "serviceContext": {
        "service": string,     // Required.
        "version": string
      },
      "message": string,       // Required. Should contain the full exception
                               // message, including the stack trace.
      "@type": string          // Optional.  Review "Specifying @type" section above.
      "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
        }
      }
    }

Unterstützte überwachte Ressourcentypen

Beim Logging über die LogEntry-Struktur muss das Feld resource auf einen der folgenden unterstützten überwachten Ressourcentypen festgelegt werden:

  • app_script_function
  • aws_ec2_instance
  • cloud_function
  • cloud_run_revision
  • consumed_api
  • container
  • dataflow_step
  • gae_app
  • gce_instance
  • k8s_container
  • ml_job1
  • global1

1 textPayload wird nicht unterstützt

Beispiele für die Formatierung von Logeinträgen

Die folgenden Beispiele zeigen Logeinträge, die korrekt von Error Reporting verarbeitet werden, wenn sie in LogEntry.jsonPayload protokolliert werden.

Dieser Logeintrag wird gruppiert, da der @type korrekt angegeben ist:

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

Die Nutzlast-message dieses Logeintrags enthält einen Stacktrace und eine Ausnahme. Daher wird sie ebenfalls von Error Reporting gruppiert:

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

Ausführliche Informationen zu den Feldern, die in einer Instanz von ReportedErrorEvent verwendet werden, finden Sie in der Dokumentation.