Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定記錄項目格式，回報錯誤事件

您可以設定 Cloud Logging 記錄項目的格式，讓 Error Reporting 自動擷取及分組應用程式錯誤，協助您監控及診斷服務問題。

使用 Cloud Logging 寫入記錄項目時，LogEntry 物件必須包含堆疊追蹤或格式化的 ReportedErrorEvent 物件。請參閱下列各節，瞭解如何設定文字酬載和 JSON 欄位 (例如 message、stack_trace 和 @type) 的格式，確保 Error Reporting 功能正確剖析及分組錯誤事件。

事前準備

請按照您的語言和平台的設定操作說明操作。
如果您需要以 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。

如果系統評估 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_job¹
workflows.googleapis.com/Workflow
global¹

¹textPayload 不支援

範例

本節說明如何確保 Error Reporting 在記錄項目含有文字訊息或堆疊追蹤時，會處理該記錄項目。

記錄文字訊息的錯誤事件

如要記錄文字訊息的錯誤事件，請使用 jsonPayload 欄位的下列 JSON 結構，格式化 LogEntry 物件：

{...
  {
    "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 物件中，請使用下列 JSON 結構做為 LogEntry 的 jsonPayload 欄位：

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

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