此页面由 Cloud Translation API 翻译。

设置日志中错误的格式

本文档介绍了在使用 Cloud Logging，用于报告错误事件。

您可以通过执行 Cloud Logging API 方法 write 或 Error Reporting API 方法 report 将错误事件报告给 Google Cloud 项目。使用 Cloud Logging API 报告错误事件时，请求正文包含一个 LogEntry 对象（必须包含堆栈轨迹）或 ReportedErrorEvent 对象。

准备工作

按照适用于您所用语言和平台的设置说明进行操作。
如果您需要基于 API 密钥的身份验证，则必须使用 Error Reporting API。要使用 Error Reporting API，执行方法 report 并将方法请求正文的格式设置为 ReportedErrorEvent 对象。

使用 Error Reporting API 时，系统会自动生成包含格式正确的错误消息的日志条目，并将其写入 Cloud Logging。这些日志条目会写入到其 logName 的格式如下：
```
projects/PROJECT_ID/clouderrorreporting.googleapis.com%2Freported_errors
```
由于日志条目是通过调用 report 生成的，因此可能会产生 Cloud Logging 注入费用。如需控制提取哪些日志，请参阅排除过滤条件。

如果您使用 Error Reporting API 报告错误事件，则本文档的其余部分不适用。

`LogEntry` 格式要求

本部分介绍了如何设置 LogEntry 的格式， Error Reporting 会捕获所包含的错误事件。

记录堆栈轨迹

要记录属于堆栈轨迹的错误事件，请将以下错误事件之一：

多行 textPayload。
包含 message、stack_trace 或 exception 的 jsonPayload 字段。

您可以指定其中多个字段。如果其中不止一个字段，则评估顺序为： stack_trace，之后价格为 exception，最后价格为 message。

如果错误事件的格式为 ReportedErrorEvent 对象，请将其字段复制到 jsonPayload。有关详情和示例，请参阅记录格式为 ReportedErrorEvent 对象的错误。
不包含 message、stack_trace 或jsonPayload exception 字段，但包含堆栈轨迹。

Error Reporting 会在 jsonPayload 中的所有字段内搜索堆栈轨迹如果找到多个堆栈轨迹，则找到一个堆栈轨迹 Trace 已选中。选择算法可确保一致的选择。

记录短信

要记录文本消息形式的错误事件，请使用以下格式 jsonPayload:

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

当您将 @type 字段设置为指定值时，Error Reporting 始终会评估日志条目，就好像所有必需字段均已存在一样。因此 Error Reporting 会捕获错误事件。

如果您将 @type 字段设置为其他值或未设置，然后使用 Cloud Logging 搜索标记为 serviceContext 的字段，以确定载荷是否 ReportedErrorEvent 对象。

当 message、stack_trace、@type 或 exception 字段包含堆栈轨迹。jsonPayload 在这些情况下，Error Reporting 会自动捕获错误事件。

支持的受监控资源

将 LogEntry 对象的 resource 字段设置为以下受支持的受监控资源类型之一：

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

示例

本部分介绍如何确保 Error Reporting 在以下情况下处理日志条目：日志条目包含文本消息或堆栈轨迹。

记录文本消息形式的错误事件

以下示例展示了如何设置 LogEntry 对象的格式。如果您要记录文本消息形式的错误事件，请为 LogEntry 的 jsonPayload 字段使用以下 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"
  }
}

如示例所示，您必须将 @type 字段设置为 Error Reporting 对日志条目进行分组：如需了解详情，请参阅记录短信。

当 message 字段包含堆栈轨迹时，相应日志条目会自动分组，因此您无需指定 @type 字段。

记录格式为 `ReportedErrorEvent` 对象的错误

当您的错误事件存储在 ReportedErrorEvent 中时对象的 jsonPayload 字段，请使用以下 JSON 结构 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
    }
  }
}

务必使用错误信息填充 message 字段。如需了解如何将堆栈轨迹存储在 ReportedErrorEvent 对象的 message 字段中，请参阅 report 方法的参考页面。

以下示例说明了如何设置 jsonPayload 字段的将 LogEntry 格式化为 ReportedErrorEvent 对象。由于 message 字段包含堆栈轨迹，错误事件按 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"
}

使用 `textPayload` 字段记录错误事件

您可以使用 LogEntry 的 textPayload 字段来记录错误事件用于存储错误数据。例如：以下 Google Cloud CLI 命令会生成日志条目，其中严重级别为 ERROR，并且其 textPayload 字段包含发生错误：

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

上一条命令的结果是按照 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)"
    ...
}