Memformat entri log untuk melaporkan peristiwa error

Dokumen ini menjelaskan cara memformat entri log saat Anda ingin menggunakan Cloud Logging untuk melaporkan peristiwa error.

Anda dapat melaporkan peristiwa error ke project Google Cloud dengan mengeksekusi metode Cloud Logging API write atau metode Error Reporting API report. Saat Anda melaporkan peristiwa error menggunakan Cloud Logging API, isi permintaan berisi objek LogEntry yang harus menyertakan pelacakan tumpukan, atau objek ReportedErrorEvent.

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, bagian dokumen ini tidak berlaku.

Persyaratan format LogEntry

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

Mencatat stack trace

Untuk mencatat peristiwa error yang merupakan trace stack, 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 pesan dievaluasi dan tidak kosong, maka stack trace hanya diambil jika kolom tersebut berisi stack trace dalam salah satu format bahasa pemrograman yang didukung. Stack trace tidak direkam 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 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. Akibatnya, Pelaporan Error merekam peristiwa error.

Jika Anda menetapkan kolom @type ke nilai yang berbeda atau membiarkannya tidak ditetapkan, 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 dipantau 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 Error Reporting memproses entri log saat entri log tersebut berisi pesan teks atau stack trace.

Mencatat peristiwa error yang berupa pesan teks

Contoh berikut menunjukkan cara memformat objek LogEntry saat Anda ingin mencatat peristiwa error yang berupa pesan teks, gunakan struktur JSON berikut untuk kolom jsonPayload dari 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"
  }
}

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 ke dalam log.

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