You can format Cloud Logging log entries so that Error Reporting
automatically captures and groups your application errors, helping you monitor
and diagnose issues across your services.

When you write log entries by using Cloud Logging, the `LogEntry` object must
contain a stack trace or a formatted `ReportedErrorEvent` object. Use the
following sections to format text payloads and JSON fields---such as `message`,
`stack_trace`, and `@type`---so that Error Reporting correctly
parses and groups your error events.

## Before you begin

- Follow the [setup instructions](https://docs.cloud.google.com/error-reporting/docs/setup.md.txt) 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`](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt)
  and format the request body of the method as a
  [`ReportedErrorEvent`](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt#ReportedErrorEvent) object.

  When you use the Error Reporting API, log entries with properly
  formatted error messages are automatically generated and written to
  [Cloud Logging](https://docs.cloud.google.com/logging/docs.md.txt). 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 log entries are ingested,
  see [Exclusion filters](https://docs.cloud.google.com/logging/docs/routing/overview.md.txt#exclusions).

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

## `LogEntry` format requirements

This section describes how to format a [`LogEntry`](https://docs.cloud.google.com/logging/docs/api/reference/rest/v2/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](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt#ReportedErrorEvent).
  The stack trace isn't captured by Error Reporting
  when an unsupported format is used.

  If your error event is formatted as a
  [`ReportedErrorEvent`](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt#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](https://docs.cloud.google.com/error-reporting/docs/formatting-error-messages.md.txt#reported-error-example).
- 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`:

```json
    "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 a field labeled `serviceContext` to determine whether the payload
is a `ReportedErrorEvent` object.

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

### Supported monitored resources

Set the `resource` field of the [`LogEntry`](https://docs.cloud.google.com/logging/docs/api/reference/rest/v2/LogEntry) object
to one of the following supported
[monitored resource types](https://docs.cloud.google.com/logging/docs/api/v2/resource-list.md.txt#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`^1^
- `workflows.googleapis.com/Workflow`
- `global`^1^

^1^`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

To log an error event that is a text message, format the `LogEntry` object
by using the following JSON structure for the `jsonPayload` field:

```json
{...
  {
    "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](https://docs.cloud.google.com/error-reporting/docs/grouping-errors.md.txt#how_errors_are_grouped) the log entry.
For more information, see [Log a text message](https://docs.cloud.google.com/error-reporting/docs/formatting-error-messages.md.txt#log-text).

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`](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt#ReportedErrorEvent)
object, use the following JSON structure for the `jsonPayload` field of
the `LogEntry`:

```json
{
  "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`](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt#ReportedErrorEvent) object, see the
reference page for the
[`report`](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt)
method.

The following example illustrates how to set the `jsonPayload` field of the
`LogEntry` to be formatted as a `ReportedErrorEvent` object.
Because the `message` field contains a stack trace,
the error event is [grouped](https://docs.cloud.google.com/error-reporting/docs/grouping-errors.md.txt#how_errors_are_grouped) by Error Reporting:

```json
{...
   "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 message, such as a stack trace. 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:

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