本頁面由 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 物件的錯誤」。
jsonPayload 不含 message、stack_trace 或 exception 欄位，但包含堆疊追蹤。

錯誤回報會搜尋 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 不支援

範例

本節說明如何確保記錄項目包含文字訊息或堆疊追蹤記錄時，錯誤回報服務會處理該記錄項目。

記錄文字訊息形式的錯誤事件

以下範例說明如何在您想要記錄文字訊息型態的錯誤事件時，設定 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 欄位設為強制要求錯誤回報功能群組記錄項目的值：詳情請參閱「記錄文字訊息」。

如果 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)'

先前指令的結果是依據錯誤回報分組的記錄項目：

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

記錄中的格式錯誤 透過集合功能整理內容 你可以依據偏好儲存及分類內容。