Formatting errors in Stackdriver Logging

This page explains the log entry format required for using Stackdriver Logging to report error events.

Before you begin

If using the Stackdriver Error Reporting API, you can report error events from your application by writing them to ReportedErrorEvent. Doing this generates log entries with properly formatted error messages in Stackdriver Logging. The resulting logName is formatted as:

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

You might incur Stackdriver Logging ingestion costs using this method; to control these costs, review Logs exclusions.

If you prefer to use Stackdriver Logging to report error events, read the following sections.

Formatting requirements

Log entries in Stackdriver Logging that contain stack traces or exceptions, or that are formatted like ReportedErrorEvent, generate errors in Error Reporting.

Error data should be logged to the LogEntry union field payload, as one of these types:

• A multi-line textPayload
• The message field of jsonPayload

You must also follow the setup instructions for your language and platform. When logging error data from App Engine, Compute Engine, and Google Kubernetes Engine, the only formatting requirement is that the log entry contains the full exception message and stack trace.

Specifying @type

If your log entry contains the @type of type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent, then Error Reporting evaluates the log entry as though all required fields are present and captures the error event:

JSON representation

When sending error data using Stackdriver Logging, the ReportedErrorEvent you provide must use the following JSON structure:

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

Key Point: In addition to or instead of message, you can provide the stack_trace or exception properties. If more than one of these properties are provided, then the order of evaluation is: stack_trace, then exception, and then message.

Supported monitored resource types

When logging via the LogEntry structure, the resource field must be set to one of the following supported monitored resource types:

• app_script_function
• aws_ec2_instance
• cloud_function
• cloud_run_revision
• consumed_api
• container
• dataflow_step
• gae_app
• gce_instance
• k8s_container
• ml_job¹
• global¹

¹ textPayload not supported

Log entry formatting examples

The following examples illustrate log entries that are correctly processed by Error Reporting if logged in LogEntry.jsonPayload.

This log entry is grouped, because the @type is properly specified:

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

This log entry's payload message contains a stack trace and exception, so it is also grouped by Stackdriver Error Reporting:

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

For details on the fields used in an instance of ReportedErrorEvent, refer to the documentation.