Format errors in logs

This document explains how to format the log entry when you want to use Cloud Logging to report error events.

You can report error events to your Google Cloud project by executing the Cloud Logging API method write or the Error Reporting API method report. When you report error events by using the Cloud Logging API, then request body contains a LogEntry object that must include a stack trace, or a ReportedErrorEvent object.

Before you begin

Follow the setup instructions for your language and platform.
If you require API key-based authentication, then you must use the Error Reporting API. To report an error event by using the Error Reporting API, execute the method report and format the request body of the method as a ReportedErrorEvent object.

When you use the Error Reporting API, log entries with properly formatted error messages are automatically generated and written to Cloud Logging. These log entries are written to a log whose logName is formatted as follows:
```
projects/PROJECT_ID/clouderrorreporting.googleapis.com%2Freported_errors
```
Because log entries are generated by calls to report, you might incur Cloud Logging ingestion costs. To control which logs are ingested, see Exclusion filters.

If you report error events by using the Error Reporting API, the remainder of this document doesn't apply.

`LogEntry` format requirements

This section describes how to format a LogEntry so that Error Reporting captures the error event that is contained in the log entry.

Log a stack trace

To log an error event that is a stack trace, write the error event as one of these types:

A multi-line textPayload.
A jsonPayload that includes a message, stack_trace, or exception field.

You can specify more than one of those fields. If more than one of those fields is specified, then the order of evaluation is: stack_trace, then exception, and then message.

If the message field is evaluated and if it isn't empty, then the stack trace is captured only when the field contains a stack trace in one of the supported programming language formats. The stack trace isn't captured by Error Reporting when an unsupported format is used.

If your error event is formatted as a ReportedErrorEvent object, then copy its fields to the jsonPayload. For more information and an example, see Log an error that is formatted as a ReportedErrorEvent object.
A jsonPayload that doesn't include a message, stack_trace, or exception field, but does include a stack trace.

Error Reporting searches all fields in a jsonPayload for stack traces. If more than one stack trace is found, then one stack trace is selected. The selection algorithm ensures a consistent choice.

Log a text message

To log an error event that is a text message, use the following format for the jsonPayload:

    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "Text message"
    },

When you set the @type field to the specified value, Error Reporting always evaluates the log entry as though all required fields are present. As a result, Error Reporting captures the error event.

If you set the @type field to a different value or leave it unset, then Cloud Logging searches for field labeled serviceContext to determine if the payload is a ReportedErrorEvent object.

You don't need to set the @type field when the message, stack_trace, or exception fields of the jsonPayload contain a stack trace. In those cases, Error Reporting automatically captures the error event.

Supported monitored resources

Set the resource field of the LogEntry object to one of the following supported monitored resource types:

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_job¹
workflows.googleapis.com/Workflow
global¹

¹textPayload not supported

Examples

This section shows how you can ensure that Error Reporting processes a log entry when that log entry contains a text message or a stack trace.

Log an error event that is a text message

The following example shows how to format a LogEntry object when you want to log an error event that is a text message, use the following JSON structure for the jsonPayload field of the 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"
  }
}

As the example shows, you must set the @type field to the value that forces Error Reporting to group the log entry: For more information, see Log a text message.

When the message field contains a stack trace, the log entry is automatically grouped so you don't need to specify the @type field.

Log an error that is formatted as a `ReportedErrorEvent` object

When your error event is stored in a ReportedErrorEvent object, use the following JSON structure for the jsonPayload field of the 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
    }
  }
}

Ensure that you populate the message field with the error information. To learn how to store a stack trace in the message field of a ReportedErrorEvent object, see the reference page for the report method.

The following example illustrates how to set the jsonPayload field of the LogEntry to be formatted as an ReportedErrorEvent object. Because the message field contains a stack trace, the error event is grouped by Error Reporting:

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

Log an error event by using the `textPayload` field

You can record an error event by using the textPayload field of a LogEntry to store the error data. For example, the following Google Cloud CLI command results in a log entry whose severity level is ERROR and whose textPayload field contains an error event:

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

The result of the previous command is a log entry that is grouped by Error Reporting:

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