Memformat entri log untuk melaporkan peristiwa error

Anda dapat memformat entri log Cloud Logging sehingga Error Reporting otomatis merekam dan mengelompokkan error aplikasi Anda, sehingga membantu Anda memantau dan mendiagnosis masalah di seluruh layanan Anda.

Saat Anda menulis entri log menggunakan Cloud Logging, objek LogEntry harus berisi stack trace atau objek ReportedErrorEvent yang diformat. Gunakan bagian berikut untuk memformat payload teks dan kolom JSON—seperti message, stack_trace, dan @type—agar Pelaporan Error mem-parsing dan mengelompokkan peristiwa error Anda dengan benar.

Sebelum memulai

  • Ikuti petunjuk penyiapan untuk bahasa dan platform Anda.

  • Jika memerlukan autentikasi berbasis kunci API, Anda harus menggunakan Error Reporting API. Untuk melaporkan peristiwa error menggunakan Error Reporting API, jalankan metode report dan format isi permintaan metode sebagai objek ReportedErrorEvent.

    Saat Anda menggunakan Error Reporting API, entri log dengan pesan error yang diformat dengan benar akan otomatis dibuat dan ditulis ke Cloud Logging. Entri log ini ditulis ke log yang logName-nya diformat sebagai berikut:

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

    Karena entri log dihasilkan oleh panggilan ke report, Anda mungkin dikenai biaya penyerapan Cloud Logging. Untuk mengontrol entri log yang diserap, lihat Filter pengecualian.

    Jika Anda melaporkan peristiwa error menggunakan Error Reporting API, maka bagian dokumen ini selanjutnya tidak berlaku.

Persyaratan format LogEntry

Bagian ini menjelaskan cara memformat LogEntry sehingga Error Reporting merekam peristiwa error yang ada dalam entri log.

Mencatat stack trace

Untuk mencatat peristiwa error yang merupakan stack trace, tulis peristiwa error sebagai salah satu jenis berikut:

  • Multi-baris textPayload.

  • jsonPayload yang menyertakan kolom message, stack_trace, atau exception.

    Anda dapat menentukan lebih dari satu kolom tersebut. Jika lebih dari satu kolom tersebut ditentukan, urutan evaluasinya adalah: stack_trace, lalu exception, dan kemudian message.

    Jika kolom message dievaluasi dan tidak kosong, maka trace stack hanya diambil saat kolom berisi trace stack dalam salah satu format bahasa pemrograman yang didukung. Stack trace tidak diambil oleh Error Reporting saat format yang tidak didukung digunakan.

    Jika peristiwa error Anda diformat sebagai objek ReportedErrorEvent, salin kolomnya ke jsonPayload. Untuk mengetahui informasi selengkapnya dan contohnya, lihat Mencatat error yang diformat sebagai objek ReportedErrorEvent.

  • jsonPayload yang tidak menyertakan kolom message, stack_trace, atau exception, tetapi menyertakan stack trace.

    Error Reporting menelusuri semua kolom dalam jsonPayload untuk stack trace. Jika lebih dari satu rekaman aktivitas ditemukan, maka salah satu rekaman aktivitas akan dipilih. Algoritma pemilihan memastikan pilihan yang konsisten.

Mencatat pesan teks

Untuk mencatat peristiwa error yang berupa pesan teks, gunakan format berikut untuk jsonPayload:

    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "Text message"
    },

Saat Anda menyetel kolom @type ke nilai yang ditentukan, Pelaporan Error selalu mengevaluasi entri log seolah-olah semua kolom wajib diisi ada. Akibatnya, Pelaporan Error merekam peristiwa error.

Jika Anda menyetel kolom @type ke nilai yang berbeda atau membiarkannya tidak disetel, maka Cloud Logging akan menelusuri kolom berlabel serviceContext untuk menentukan apakah payload adalah objek ReportedErrorEvent.

Anda tidak perlu menetapkan kolom @type jika kolom message, stack_trace, atau exception dari jsonPayload berisi stack trace. Dalam kasus tersebut, Error Reporting akan otomatis merekam peristiwa error.

Resource yang dimonitor yang didukung

Tetapkan kolom resource objek LogEntry ke salah satu jenis resource yang dimonitor yang didukung berikut:

  • 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_job1
  • workflows.googleapis.com/Workflow
  • global1

1 textPayload tidak didukung

Contoh

Bagian ini menunjukkan cara Anda dapat memastikan bahwa Pelaporan Error memproses entri log saat entri log tersebut berisi pesan teks atau stack trace.

Mencatat peristiwa error yang berupa pesan teks

Untuk mencatat peristiwa error yang berupa pesan teks, format objek LogEntry menggunakan struktur JSON berikut untuk kolom 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"
  }
}

Seperti yang ditunjukkan contoh, Anda harus menetapkan kolom @type ke nilai yang memaksa Pelaporan Error untuk mengelompokkan entri log. Untuk mengetahui informasi selengkapnya, lihat Mencatat pesan teks.

Jika kolom message berisi pelacakan tumpukan, entri log akan dikelompokkan secara otomatis, sehingga Anda tidak perlu menentukan kolom @type.

Mencatat error yang diformat sebagai objek ReportedErrorEvent

Jika peristiwa error Anda disimpan dalam objek ReportedErrorEvent, gunakan struktur JSON berikut untuk kolom jsonPayload dari LogEntry:

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

Pastikan Anda mengisi kolom message dengan informasi error. Untuk mempelajari cara menyimpan pelacakan tumpukan di kolom message objek ReportedErrorEvent, lihat halaman referensi untuk metode report.

Contoh berikut mengilustrasikan cara menyetel kolom jsonPayload dari LogEntry agar diformat sebagai objek ReportedErrorEvent. Karena kolom message berisi stack trace, peristiwa error dikelompokkan oleh 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"
}

Mencatat peristiwa error menggunakan kolom textPayload

Anda dapat merekam peristiwa error dengan menggunakan kolom textPayload dari LogEntry untuk menyimpan pesan error, seperti pelacakan tumpukan. Misalnya, perintah Google Cloud CLI berikut menghasilkan entri log yang tingkat keparahan adalah ERROR dan kolom textPayload-nya berisi peristiwa error:

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

Hasil perintah sebelumnya adalah entri log yang dikelompokkan menurut Pelaporan Error:

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