设置日志条目的格式以报告错误事件

本文档介绍了当您想使用 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。

    如果系统评估了消息字段，并且该字段不为空，则仅当该字段包含支持的某种编程语言格式的堆栈轨迹时，才会捕获堆栈轨迹。如果使用不受支持的格式，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

示例

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

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

以下示例展示了如何设置 LogEntry 对象的格式，以便在您想要记录文本消息形式的错误事件时，使用以下 JSON 结构作为 LogEntry 的 jsonPayload 字段：

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

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