Format errors in logs

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

Before you begin

If you're 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 follows:

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

You might incur Cloud Logging ingestion costs using this method. To control ingestion, see Logging Routing and storage overview: Exclusion filters.

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

Formatting requirements

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

If the log entry specifies @type, then the payload field might contain just a simple text message rather than complex error data.

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, see the ReportedErrorEvent section on the report reference page for Error Reporting.

Specify @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 main error content to report.
                           // For information on populating this field, see Formatting requirements.
  "@type": string          // Optional. For information on this field, see Specify @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
• k8s_pod
• ml_job¹
• workflows.googleapis.com/Workflow
• 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, see the the documentation.