设置日志中错误的格式

本文档介绍了在使用 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
  • 包含 messagestack_traceexceptionjsonPayload 字段。

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

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

  • 不包含 messagestack_tracejsonPayload 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 对象。

messagestack_trace@typeexception 字段包含堆栈轨迹。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_job1
  • workflows.googleapis.com/Workflow
  • global1

1 不支持 textPayload

示例

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

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

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

您可以使用 LogEntrytextPayload 字段来记录错误事件 用于存储错误数据。例如: 以下 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)"
    ...
}