Error format di log

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 menjalankan metode Cloud Logging API write atau metode Error Reporting API report. Saat Anda melaporkan peristiwa error menggunakan Cloud Logging API, isi permintaan akan 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 log yang akan diserap, lihat Filter pengecualian.

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

Persyaratan format LogEntry

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

Mencatat pelacakan tumpukan ke dalam log

Untuk mencatat peristiwa error yang merupakan pelacakan tumpukan, tulis peristiwa error sebagai salah satu jenis berikut:

  • textPayload multibaris.

  • 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, lalu message.

    Jika kolom pesan dievaluasi dan tidak kosong, rekaman aktivitas stack hanya akan diambil jika kolom berisi rekaman aktivitas 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 informasi selengkapnya dan contoh, lihat Mencatat error yang diformat sebagai objek ReportedErrorEvent.

  • jsonPayload yang tidak menyertakan kolom message, stack_trace, atau exception, tetapi menyertakan pelacakan tumpukan.

    Pelaporan Error menelusuri semua kolom di jsonPayload untuk pelacakan tumpukan. Jika lebih dari satu pelacakan tumpukan ditemukan, satu pelacakan tumpukan akan dipilih. Algoritma pemilihan memastikan pilihan yang konsisten.

Mencatat pesan teks ke dalam log

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 menetapkan kolom @type ke nilai yang ditentukan, Pelaporan Error selalu mengevaluasi entri log seolah-olah semua kolom yang diperlukan ada. Akibatnya, Pelaporan Error akan 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 pelacakan tumpukan. Dalam kasus tersebut, Pelaporan Error akan otomatis merekam peristiwa error.

Resource yang dimonitor dan 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 memastikan bahwa Pelaporan Error memproses entri log saat entri log tersebut berisi pesan teks atau pelacakan tumpukan.

Mencatat peristiwa error yang berupa pesan teks

Contoh berikut menunjukkan cara memformat objek LogEntry saat Anda ingin mencatat peristiwa error yang merupakan 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 informasi selengkapnya, lihat Mencatat pesan teks ke dalam log.

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

Mencatat error yang diformat sebagai objek ReportedErrorEvent

Saat 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 menetapkan kolom jsonPayload dari LogEntry untuk diformat sebagai objek ReportedErrorEvent. Karena kolom message berisi pelacakan tumpukan, peristiwa error dikelompokkan oleh Pelaporan Error:

{...
   "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 ke dalam log menggunakan kolom textPayload

Anda dapat merekam peristiwa error menggunakan kolom textPayload dari LogEntry untuk menyimpan data error. Misalnya, perintah Google Cloud CLI berikut menghasilkan entri log dengan tingkat keparahan ERROR dan kolom textPayload yang 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)"
    ...
}