Formatting errors in logs

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

Before you begin

If using the 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 Cloud Logging. The resulting logName is formatted as:

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

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

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

Formatting requirements

Log entries in Cloud 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.

To learn how to format the exception message and stack trace, go to the ReportedErrorEvent section on the report reference page for Error Reporting.

Specifying @type

If your log entry contains a field with an @type specifier, and the value for that specifier is 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 Cloud Logging, the ReportedErrorEvent you provide must use the following JSON structure:

{
  "eventTime": string,
  "serviceContext": {
    "service": string,     // Required.
    "version": string
  },
  "message": string,       // Required. This field contains the content to report.
                           // For information on populating this field, see  Formatting requirements.
  "@type": string          // Optional. For information on this field, see Specifying @type.
  "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": "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"
  }
}

This log entry's payload message contains a stack trace and exception, so it is also grouped by 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.