设置日志中错误的格式

本页面介绍了使用 Cloud Logging 报告错误事件时,需要使用的日志条目格式。

准备工作

如果使用 Error Reporting API,您可以通过将错误事件写入 ReportedErrorEvent 来报告错误事件。采用这种做法时,系统会在 Cloud Logging 中生成包含具有适当格式设置的错误消息的日志条目。所得到的 logName 格式如下:

  projects/<PROJECT_ID>/clouderrorreporting.googleapis.com%2Freported_errors

采用这种方法时,可能会产生 Cloud Logging 提取费用;要控制这些费用,请参阅日志排除项

如果您希望使用 Cloud Logging 报告错误事件,请参阅以下部分。

格式设置要求

在 Cloud Logging 中,包含堆栈轨迹、异常跟踪或者采用类似于 ReportedErrorEvent 的格式的日志条目会在 Error Reporting 中生成错误。

错误数据应记录到以下类型之一的 LogEntry 联合字段 payload 中。

  • 多行 textPayload
  • jsonPayloadmessage 字段

您还必须按照适用于您所用语言和平台的设置说明执行操作。在日志中记录 App EngineCompute EngineGoogle Kubernetes Engine 提供的错误数据时,唯一的格式要求是日志条目要包含完整的异常消息和堆栈轨迹。

如需了解如何为异常消息和堆栈轨迹设置格式,请参阅 Error Reporting 的 report 参考页面上的 ReportedErrorEvent 部分。

指定 @type

如果您的日志条目包含 type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent@type,则 Error Reporting 会评估日志条目,就像所有必填字段均已存在并且捕获了错误事件一样。

JSON 表示

使用 Cloud Logging 发送错误数据时,您提供的 ReportedErrorEvent 必须使用以下 JSON 结构:

    {
      "eventTime": string,
      "serviceContext": {
        "service": string,     // Required.
        "version": string
      },
      "message": string,       // Required. Should contain the full exception
                               // message, including the stack trace.
      "@type": string          // Optional.  Review "Specifying @type" section above.
      "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
        }
      }
    }

支持的受监控资源类型

通过 LogEntry 结构记录日志时,resource 字段必须设置为支持的受监控资源类型之一:

  • app_script_function
  • aws_ec2_instance
  • cloud_function
  • cloud_run_revision
  • consumed_api
  • container
  • dataflow_step
  • gae_app
  • gce_instance
  • k8s_container
  • ml_job1
  • global1

1 不支持 textPayload

日志条目格式设置示例

以下示例展示了在登录到 LogEntry.jsonPayload 后,经过 Error Reporting 正确处理的日志条目。

由于正确指定了 @type,此日志条目已分组:

{...
  {
    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "An error message without stacktrace or exception"
    },
    "logName": "projects/test-project/logs/reported-error",
    "resource": {
      "labels": {
        "project_id": "test-project"
      },
      "type": "global"
    },
    "severity": "ERROR",
    "timestamp": "2019-06-27T13:43:26.375834551Z"
  }
}

此日志条目的载荷 message 包含堆栈轨迹和异常,因此也会被 Error Reporting 分组:

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

如需详细了解 ReportedErrorEvent 实例中所用的字段,请参阅文档