设置日志中错误的格式

本文档介绍了当您想要使用 Cloud Logging 报告错误事件时，如何设置日志条目的格式。

您可以 Google Cloud 通过执行 Cloud Logging API 方法 write 或 Error Reporting API 方法 report 来向项目报告错误事件。使用 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。

    如果系统对消息字段进行了求值，并且该字段不为空，则只有当该字段包含某种受支持的编程语言格式的堆栈轨迹时，系统才会捕获堆栈轨迹。使用不受支持的格式时，Error Reporting 不会捕获堆栈轨迹。

    如果错误事件的格式为 ReportedErrorEvent 对象，请将其字段复制到 jsonPayload。如需了解详情和示例，请参阅记录格式为 ReportedErrorEvent 对象的错误。

  • 不包含 message、stack_trace 或 exception 字段，但包含堆栈轨迹的 jsonPayload。

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

记录短信

如需记录文本消息形式的错误事件，请使用以下格式为 jsonPayload 设置参数：

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

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

如果您将 @type 字段设置为其他值或将其保持未设置状态，则 Cloud Logging 会搜索标记为 serviceContext 的字段，以确定载荷是否为 ReportedErrorEvent 对象。

如果 jsonPayload 的 message、stack_trace 或 exception 字段包含堆栈轨迹，则无需设置 @type 字段。在这些情况下，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_job1
  • workflows.googleapis.com/Workflow
  • global1

1 不支持 textPayload

示例

本部分介绍了如何确保当日志条目包含文本消息或堆栈轨迹时，错误报告会处理该日志条目。

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

以下示例展示了如何设置 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 对象中时，请为 LogEntry 的 jsonPayload 字段使用以下 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
    }
  }
}

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

以下示例展示了如何将 LogEntry 的 jsonPayload 字段设置为 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)'

上一个命令的结果是按错误报告分组的日志条目：

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