ログでエラーをフォーマットする

このドキュメントでは、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` 形式の要件

このセクションでは、Error Reporting がログエントリに含まれるエラーイベントをキャプチャできるように、LogEntry をフォーマットする方法について説明します。

スタックトレースをログに記録する

スタックトレースであるエラーイベントをログに記録するには、エラーイベントを次のいずれかのタイプとして記述します。

複数行の textPayload。
message、stack_trace、exception フィールドを含む jsonPayload。

これらのフィールドは複数指定できます。これらのフィールドが複数指定されている場合、評価は stack_trace、exception、message の順に行われます。

エラーイベントが ReportedErrorEvent オブジェクトとして形式設定されている場合は、そのフィールドを jsonPayload にコピーします。詳細と例については、ReportedErrorEvent オブジェクトとしてフォーマットされたエラーをログに記録するをご覧ください。
message、stack_trace、exception フィールドを含まないものの、スタックトレースは含まれている jsonPayload。

Error Reporting は、jsonPayload 内のすべてのフィールドでスタックトレースを検索します。複数のスタックトレースが見つかった場合は、1 つのスタックトレースが選択されます。選択アルゴリズムにより、選択の一貫性が確保されます。

テキストメッセージをログに記録する

テキストメッセージのエラーイベントをログに記録するには、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 フィールドを、Error Reporting にログエントリをグループ化する値に設定する必要があります。詳細については、テキストメッセージをログに記録するをご覧ください。

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

ログでエラーをフォーマットする

始める前に

LogEntry 形式の要件

スタック トレースをログに記録する

テキスト メッセージをログに記録する