Error format dalam 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 Anda 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 dibuat oleh panggilan ke report, Anda mungkin dikenai biaya penyerapan Cloud Logging. Untuk mengontrol log yang diserap, lihat Filter pengecualian.

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

Persyaratan format `LogEntry`

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

Mencatat pelacakan tumpukan

Untuk mencatat peristiwa error yang merupakan pelacakan tumpukan ke dalam log, 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, exception, lalu message.

Jika peristiwa error Anda diformat sebagai objek ReportedErrorEvent, salin kolomnya ke jsonPayload. Untuk mengetahui informasi selengkapnya dan contoh, lihat Mencatat error yang diformat sebagai objek ReportedErrorEvent ke dalam log.
jsonPayload yang tidak menyertakan kolom message, stack_trace, atau exception, tetapi menyertakan pelacakan tumpukan.

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

Catat pesan teks

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

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

Jika Anda menetapkan kolom @type ke nilai yang ditentukan, Error Reporting selalu mengevaluasi entri log seolah-olah semua kolom wajib diisi tersedia. Akibatnya, Error Reporting akan merekam peristiwa error tersebut.

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

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

Resource yang dipantau dan didukung

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

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 tidak didukung

Contoh

Bagian ini menunjukkan cara memastikan bahwa Error Reporting memproses entri log saat entri log tersebut berisi pesan teks atau pelacakan tumpukan.

Catat peristiwa error yang berupa pesan teks

Contoh berikut menunjukkan cara memformat objek LogEntry saat Anda ingin mencatat peristiwa error yang berupa pesan teks ke dalam log, 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 dalam contoh, Anda harus menetapkan kolom @type ke nilai yang memaksa Error Reporting 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.

Catat log error yang diformat sebagai objek `ReportedErrorEvent`

Jika peristiwa error Anda disimpan di 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 dari objek ReportedErrorEvent, lihat halaman referensi untuk metode report.

Contoh berikut menggambarkan cara menetapkan kolom jsonPayload dari LogEntry untuk diformat sebagai objek ReportedErrorEvent. Karena kolom message berisi pelacakan tumpukan, peristiwa error dikelompokkan menurut 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"
}

Catat peristiwa error ke dalam log menggunakan kolom `textPayload`

Anda dapat mencatat peristiwa error menggunakan kolom textPayload dari LogEntry untuk menyimpan data error. Misalnya, perintah Google Cloud CLI berikut akan 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 dari perintah sebelumnya adalah entri log yang dikelompokkan oleh Error Reporting:

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