Menggunakan log platform untuk memecahkan masalah topik impor Cloud Storage

Panduan ini menjelaskan cara menggunakan log platform Google Cloud untuk memecahkan masalah saat Anda menggunakan topik impor Cloud Storage untuk menyerap data.

Tentang kegagalan penyerapan di topik impor Cloud Storage

Topik impor Cloud Storage dapat mengalami masalah yang mencegah data berhasil diserap. Misalnya, saat menggunakan topik impor Cloud Storage, Anda mungkin mengalami masalah saat menyerap objek Cloud Storage atau bagian dari objek.

Daftar berikut menjelaskan alasan kegagalan penyerapan dalam topik impor Cloud Storage yang menghasilkan log platform:

  • Ukuran pesan

    • Setiap pesan tidak boleh lebih besar dari 10 MB. Jika demikian, seluruh pesan akan dilewati.

    • Jika Anda menggunakan format Avro atau Pub/Sub Avro, blok pesan tidak boleh lebih besar dari 16 MB. Blok pesan yang lebih besar akan dilewati.

  • Atribut pesan

    • Pesan dapat memiliki maksimal 100 atribut. Atribut tambahan apa pun akan dihapus saat pesan diserap.

    • Kunci atribut tidak boleh lebih besar dari 256 byte dan nilai tidak boleh lebih besar dari 1024 byte. Kunci atau nilai yang lebih besar akan dihapus dari pesan saat diproses.

      Untuk informasi selengkapnya tentang panduan penggunaan kunci dan atribut pesan, lihat Menggunakan atribut untuk memublikasikan pesan.

  • Pemformatan Avro

    • Pastikan objek Avro Anda diformat dengan benar. Pemformatan yang salah akan mencegah pesan diserap.

  • Format data

Tentang log platform

Layanan Google Cloud yang didukung menghasilkan kumpulan log platformnya sendiri, yang merekam peristiwa dan aktivitas yang relevan dengan operasi layanan tersebut. Log platform ini berisi informasi mendetail tentang apa yang terjadi dalam layanan, termasuk operasi yang berhasil, error, peringatan, dan peristiwa penting lainnya.

Log platform adalah bagian dari Cloud Logging dan memiliki fitur yang sama. Misalnya, berikut adalah daftar fitur penting untuk log platform:

  • Log biasanya disusun sebagai objek JSON yang memungkinkan kueri dan pemfilteran lebih lanjut.

  • Anda dapat melihat log platform menggunakan Logging di konsol.

  • Log platform juga dapat diintegrasikan dengan Cloud Monitoring dan alat pemantauan lainnya untuk membuat dasbor, pemberitahuan, dan mekanisme pemantauan lainnya.

  • Penyimpanan log dikenai biaya berdasarkan volume yang diserap dan periode retensi.

Untuk mengetahui informasi selengkapnya tentang log platform, lihat Log platform Google Cloud.

Peran dan izin yang diperlukan untuk menggunakan log platform

Sebelum memulai, pastikan Anda memiliki akses ke Logging. Anda memerlukan peran Identity and Access Management (IAM) Logs Viewer (roles/logging.viewer). Untuk mengetahui informasi selengkapnya tentang akses logging, lihat Kontrol akses dengan IAM.

Berikut ini penjelasan cara memverifikasi dan memberikan akses IAM:

Mengaktifkan log platform

Log platform dinonaktifkan secara default untuk topik impor. Anda dapat mengaktifkan log platform saat membuat atau memperbarui topik impor Cloud Storage.

Untuk menonaktifkan log platform, update topik impor Cloud Storage.

Mengaktifkan log platform saat membuat topik impor Cloud Storage

Pastikan Anda telah menyelesaikan prasyarat untuk membuat topik impor Cloud Storage.

Untuk membuat topik impor Cloud Storage dengan log platform yang diaktifkan, ikuti langkah-langkah berikut:

Konsol

  1. Di konsol Google Cloud, buka halaman Topics.

    Buka Topik

  2. Klik Create topic.

    Halaman detail topik akan terbuka.

  3. Di kolom Topic ID, masukkan ID untuk topik impor Cloud Storage Anda.

    Untuk informasi selengkapnya tentang penamaan topik, lihat panduan penamaan.

  4. Pilih Tambahkan langganan default.

  5. Pilih Aktifkan penyerapan.

  6. Tentukan opsi untuk penyerapan dengan mengikuti petunjuk di Membuat topik impor Cloud Storage.
  7. Pilih Enable platform logs.
  8. Pertahankan setelan default lainnya.
  9. Klik Create topic.

gcloud

  1. Di konsol Google Cloud, aktifkan Cloud Shell.

    Aktifkan Cloud Shell

    Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

  2. Untuk mengaktifkan log platform, pastikan tanda --ingestion-log-severity disetel ke WARNING atau yang lebih tinggi. Jalankan perintah gcloud pubsub topics create:

    gcloud pubsub topics create TOPIC_ID\
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --ingestion-log-severity=WARNING

    Ganti kode berikut:

    • TOPIC_ID: Nama atau ID topik Anda.

    • BUCKET_NAME: Menentukan nama bucket yang ada. Contoh, prod_bucket. Nama bucket tidak boleh menyertakan project ID. Untuk membuat bucket, lihat Membuat bucket.

    • INPUT_FORMAT: Menentukan format objek yang diserap. Ini dapat berupa text, avro, atau pubsub_avro. Untuk mengetahui informasi selengkapnya tentang opsi ini, lihat Format input.

Jika Anda mengalami masalah, lihat Memecahkan masalah topik impor Cloud Storage.

Mengaktifkan log platform saat memperbarui topik impor Cloud Storage

Lakukan langkah-langkah berikut:

Konsol

  1. Di konsol Google Cloud, buka halaman Topics.

    Buka Topik

  2. Klik topik impor Cloud Storage.

  3. Di halaman detail topik, klik Edit.

  4. Pilih Enable platform logs.

  5. Klik Perbarui.

gcloud

  1. Di konsol Google Cloud, aktifkan Cloud Shell.

    Aktifkan Cloud Shell

    Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

  2. Agar tidak kehilangan setelan untuk topik impor, pastikan untuk menyertakan semuanya setiap kali Anda memperbarui topik. Jika Anda tidak memasukkan sesuatu, Pub/Sub akan mereset setelan ke nilai default aslinya.

    Untuk mengaktifkan log platform, pastikan ingestion-log-severity ditetapkan ke WARNING. Jalankan perintah gcloud pubsub topics update dengan semua flag yang disebutkan dalam contoh berikut:

    gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=WARNING

    Ganti kode berikut:

    • TOPIC_ID adalah ID atau nama topik. Kolom ini tidak dapat diperbarui.

    • BUCKET_NAME: Menentukan nama bucket yang ada. Contoh, prod_bucket. Nama bucket tidak boleh menyertakan project ID.

    • INPUT_FORMAT: Menentukan format objek yang diserap. Ini dapat berupa text, avro, atau pubsub_avro. Untuk mengetahui informasi selengkapnya tentang opsi ini, lihat Format input.

    • TEXT_DELIMITER: Menentukan pemisah untuk memisahkan objek teks menjadi pesan Pub/Sub. Kolom ini harus berupa satu karakter dan hanya boleh ditetapkan jika INPUT_FORMAT adalah text. Nilai defaultnya adalah karakter baris baru (\n).

      Saat menggunakan gcloud CLI untuk menentukan pemisah, perhatikan dengan cermat penanganan karakter khusus seperti baris baru \n. Gunakan format '\n' untuk memastikan pemisah ditafsirkan dengan benar. Cukup menggunakan \n tanpa tanda kutip atau hasil escape akan menghasilkan pemisah "n".

    • MINIMUM_OBJECT_CREATE_TIME: Menentukan waktu minimum saat objek dibuat agar dapat diserap. Format ini harus dalam UTC dalam format YYYY-MM-DDThh:mm:ssZ. Misalnya, 2024-10-14T08:30:30Z.

      Tanggal apa pun, baik masa lalu maupun masa mendatang, dari 0001-01-01T00:00:00Z hingga 9999-12-31T23:59:59Z inklusif, valid.

    • MATCH_GLOB: Menentukan pola glob yang akan dicocokkan agar objek dapat ditransfer. Saat Anda menggunakan gcloud CLI, glob pencocokan dengan karakter * harus memiliki karakter * yang diformat sebagai di-escape dalam bentuk \*\*.txt atau seluruh glob pencocokan harus dalam tanda kutip "**.txt" atau '**.txt'. Untuk mengetahui informasi tentang sintaksis yang didukung untuk pola glob, lihat dokumentasi Cloud Storage.

Menonaktifkan log platform

Lakukan langkah-langkah berikut:

Konsol

  1. Di konsol Google Cloud, buka halaman Topics.

    Buka Topik

  2. Klik topik impor Cloud Storage.

  3. Di halaman detail topik, klik Edit.

  4. Hapus centang Aktifkan log platform.

  5. Klik Perbarui.

gcloud

  1. Di konsol Google Cloud, aktifkan Cloud Shell.

    Aktifkan Cloud Shell

    Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

  2. Agar tidak kehilangan setelan untuk topik impor, pastikan untuk menyertakan semuanya setiap kali Anda memperbarui topik. Jika Anda tidak memasukkan sesuatu, Pub/Sub akan mereset setelan ke nilai default aslinya.

    Untuk menonaktifkan log platform, pastikan tingkat keparahan log penyerapan ditetapkan ke DISABLED. Jalankan perintah gcloud pubsub topics update dengan semua flag yang disebutkan dalam contoh berikut:

    gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=DISABLED

    Ganti kode berikut:

    • TOPIC_ID adalah ID atau nama topik. Kolom ini tidak dapat diperbarui.

    • BUCKET_NAME: Menentukan nama bucket yang ada. Contoh, prod_bucket. Nama bucket tidak boleh menyertakan project ID.

    • INPUT_FORMAT: Menentukan format objek yang diserap. Ini dapat berupa text, avro, atau pubsub_avro. Untuk mengetahui informasi selengkapnya tentang opsi ini, lihat Format input.

    • TEXT_DELIMITER: Menentukan pemisah untuk memisahkan objek teks menjadi pesan Pub/Sub. Kolom ini harus berupa satu karakter dan hanya boleh ditetapkan jika INPUT_FORMAT adalah text. Nilai defaultnya adalah karakter baris baru (\n).

      Saat menggunakan gcloud CLI untuk menentukan pemisah, perhatikan dengan cermat penanganan karakter khusus seperti baris baru \n. Gunakan format '\n' untuk memastikan pemisah ditafsirkan dengan benar. Cukup menggunakan \n tanpa tanda kutip atau hasil escape akan menghasilkan pemisah "n".

    • MINIMUM_OBJECT_CREATE_TIME: Menentukan waktu minimum saat objek dibuat agar dapat diserap. Format ini harus dalam UTC dalam format YYYY-MM-DDThh:mm:ssZ. Misalnya, 2024-10-14T08:30:30Z.

      Tanggal apa pun, baik masa lalu maupun masa mendatang, dari 0001-01-01T00:00:00Z hingga 9999-12-31T23:59:59Z inklusif, valid.

    • MATCH_GLOB: Menentukan pola glob yang akan dicocokkan agar objek dapat ditransfer. Saat Anda menggunakan gcloud CLI, glob pencocokan dengan karakter * harus memiliki karakter * yang diformat sebagai di-escape dalam bentuk \*\*.txt atau seluruh glob pencocokan harus dalam tanda kutip "**.txt" atau '**.txt'. Untuk mengetahui informasi tentang sintaksis yang didukung untuk pola glob, lihat dokumentasi Cloud Storage.

Melihat log platform

Untuk melihat log platform untuk topik impor Cloud Storage, lakukan tindakan berikut:

Konsol Google Cloud

  1. Di konsol Google Cloud, buka Logs Explorer.

    Buka Logs Explorer

  2. Pilih project Google Cloud.

  3. Jika diperlukan, dari menu Upgrade, beralih dari Logs Viewer Lama ke Logs Explorer.

  4. Untuk memfilter log agar hanya menampilkan entri untuk topik impor Cloud Storage, ketik resource.type="resource.type=pubsub_topic AND severity=WARNING ke kolom kueri, lalu klik Run query.

  5. Di panel Query results, klik Edit time untuk mengubah periode waktu yang akan menampilkan hasil.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Logs Explorer, lihat Menggunakan Logs Explorer.

gcloud CLI

Untuk menggunakan gcloud CLI guna menelusuri log platform untuk topik impor Cloud Storage, gunakan perintah gcloud logging read.

Tentukan filter untuk membatasi hasil Anda ke log platform untuk topik impor Cloud Storage.

gcloud logging read "resource.type=pubsub_topic AND severity=WARNING"

Cloud Logging API

Gunakan metode Cloud Logging API entries.list.

Untuk memfilter hasil agar hanya menyertakan log platform untuk topik impor Cloud Storage, gunakan kolom filter. Berikut adalah contoh objek permintaan JSON.

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"pubsub_topic\" AND severity=WARNING"
}

Melihat dan memahami format log platform

Bagian berikut menyertakan contoh log platform dan menjelaskan kolom untuk log platform.

Semua kolom khusus log platform terdapat dalam objek jsonPayload.

Kegagalan Avro 

{
  "insertId": "1xnzx8md4768",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "objectGeneration": "1661148924738910",
      "bucket": "bucket_in_avro_format",
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "avroFailureReason": {}
    },
    "topic": "projects/interpod-p2-management/topics/avro_bucket_topic",
    "errorMessage": "Unable to parse the header of the object. The object won't be ingested."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "project_id": "interpod-p2-management",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}
Kolom log Deskripsi
insertId ID unik untuk entri log.
jsonPayload.@type Mengidentifikasi jenis peristiwa. Selalu type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.cloudStorageFailure.objectGeneration Nomor pembuatan objek Cloud Storage.
jsonPayload.cloudStorageFailure.bucket Bucket Cloud Storage yang berisi objek.
jsonPayload.cloudStorageFailure.objectName Nama objek Cloud Storage.
jsonPayload.cloudStorageFailure.avroFailureReason Berisi detail error penguraian Avro yang lebih spesifik. Kolom ini dibiarkan kosong.
jsonPayload.topic Topik Pub/Sub yang menjadi tujuan pesan.
jsonPayload.errorMessage Pesan error yang dapat dibaca manusia.
resource.type Jenis resource. Selalu pubsub_topic.
resource.labels.project_id ID Project Google Cloud.
resource.labels.topic_id ID topik Pub/Sub.
timestamp Stempel waktu pembuatan entri log.
severity Tingkat keparahan yang WARNING.
logName Nama log.
receiveTimestamp Stempel waktu entri log diterima.

Kegagalan teks 

{
  "insertId": "1kc4puoag",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "bucket": "bucket_in_text_format",
      "apiViolationReason": {},
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "objectGeneration": "1727990048026758"
    },
    "topic": "projects/interpod-p2-management/topics/large_text_bucket_topic",
    "errorMessage": "The message has exceeded the maximum allowed size of 10000000 bytes. The message won't be published."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "large_text_bucket_topic",
      "project_id": "interpod-p2-management"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}
Kolom log Deskripsi
insertId ID unik untuk entri log.
jsonPayload.@type Mengidentifikasi jenis peristiwa. Selalu type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.cloudStorageFailure.objectGeneration Nomor pembuatan objek Cloud Storage.
jsonPayload.cloudStorageFailure.bucket Bucket Cloud Storage yang berisi objek.
jsonPayload.cloudStorageFailure.objectName Nama objek Cloud Storage.
jsonPayload.cloudStorageFailure.apiViolationReason Berisi detail tentang pelanggaran API. Kolom ini dibiarkan kosong.
jsonPayload.topic Topik Pub/Sub.
jsonPayload.errorMessage Pesan yang dapat dibaca manusia.
resource.type Jenis resource, selalu pubsub_topic.
resource.labels.project_id ID project Google Cloud.
resource.labels.topic_id ID topik Pub/Sub.
timestamp Stempel waktu pembuatan entri log.
severity Tingkat keparahan yang WARNING.
logName Nama log.
receiveTimestamp Waktu saat entri log diterima oleh Logging.