本頁面由 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。

如果系統評估訊息欄位後發現該欄位不為空白，則只有當欄位包含其中一種支援的程式設計語言格式的堆疊追蹤時，系統才會擷取堆疊追蹤。如果使用不支援的格式，Error Reporting 就無法擷取堆疊追蹤。

如果錯誤事件的格式為 ReportedErrorEvent 物件，請將其欄位複製到 jsonPayload。如需更多資訊和範例，請參閱「以 ReportedErrorEvent 物件格式記錄錯誤」。
不含 message、stack_trace 或 exception 欄位，但包含堆疊追蹤的 jsonPayload。

錯誤報告會搜尋 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_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 欄位設為強制錯誤報告分組記錄項目的值：詳情請參閱「記錄簡訊」。

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

設定記錄項目格式，回報錯誤事件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。