Menggunakan log platform untuk memecahkan masalah topik impor

Panduan ini menjelaskan cara menggunakan Google Cloud log platform untuk memecahkan masalah saat Anda menggunakan topik impor, termasuk hal berikut: topik impor Cloud Storage, topik impor Azure Event Hubs, topik impor Amazon MSK, dan topik impor Confluent Cloud.

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.

Sebelum memulai

Pastikan Anda telah menyelesaikan prasyarat untuk membuat topik yang Anda gunakan:

Peran dan izin yang diperlukan

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:

Tentang kegagalan penyerapan topik impor

Impor topik dapat mengalami masalah yang mencegah data berhasil ditransfer.

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 di 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 Avro tidak boleh lebih besar dari 16 MB. Blok Avro 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. Jika nilainya lebih besar dari ukuran maksimum, seluruh pasangan nilai kunci akan dihapus dari pesan saat diserap.

      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

Mengimpor topik Azure Event Hubs, Amazon MSK, dan Confluent Cloud

Topik impor Azure Event Hubs, Amazon MSK, dan Confluent Cloud dapat mengalami masalah yang mencegah data berhasil diserap.

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

  • Ukuran pesan

    • Setiap pesan tidak boleh lebih besar dari 10 MB. Jika demikian, seluruh pesan 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. Jika nilainya lebih besar dari ukuran maksimum, seluruh pasangan nilai kunci akan dihapus dari pesan saat diserap.

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

Mengaktifkan log platform

Log platform dinonaktifkan secara default untuk topik impor. Anda dapat mengaktifkan log platform saat membuat atau memperbarui topik impor. Untuk menonaktifkan log platform, perbarui topik impor.

Mengaktifkan log platform saat membuat topik impor

Untuk mengaktifkan log platform saat membuat topik impor, lakukan hal 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 Anda.

    Untuk informasi selengkapnya tentang penamaan topik, lihat panduan penamaan.

  4. Pilih Tambahkan langganan default.

  5. Pilih Aktifkan penyerapan.

  6. Pertahankan setelan default lainnya.
  7. Klik Create topic.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Untuk mengaktifkan log platform, pastikan flag --ingestion-log-severity ditetapkan ke WARNING atau tingkat keparahan yang lebih rendah seperti INFO atau DEBUG. Jalankan perintah gcloud pubsub topics create untuk topik masing-masing yang Anda gunakan:

    Misalnya, untuk mengaktifkan log platform di topik impor Cloud Storage, sertakan tanda --ingestion-log-severity=WARNING dalam perintah gcloud pubsub topics create Anda.

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

Mengaktifkan log platform saat memperbarui topik impor

Untuk mengaktifkan log platform saat memperbarui topik impor, lakukan hal berikut:

Konsol

  1. Di konsol Google Cloud, buka halaman Topics.

    Buka Topik

  2. Klik topik impor masing-masing yang Anda gunakan (topik impor Cloud Storage, topik impor Azure Event Hubs, topik impor Amazon MSK, atau topik impor Confluent Cloud).

  3. Di halaman detail topik, klik Edit.

  4. Pilih Aktifkan log platform.

  5. Klik Perbarui.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Untuk mengaktifkan log platform, pastikan tingkat keparahan log penyerapan ditetapkan ke WARNING atau tingkat keparahan yang lebih rendah seperti INFO atau DEBUG. Jalankan perintah gcloud pubsub topics update dengan semua kemungkinan flag yang menentukan setelan untuk masing-masing topik yang Anda gunakan:

    Misalnya, untuk memperbarui log di topik impor Cloud Storage yang ada, sertakan tanda --ingestion-log-severity=WARNING dalam perintah gcloud pubsub topics create Anda dan sertakan semua kemungkinan nilai tanda yang menentukan setelan untuk topik impor Cloud Storage.

    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

Menonaktifkan log platform

Untuk menonaktifkan log platform untuk masing-masing topik impor yang Anda gunakan, lakukan hal berikut:

Konsol

  1. Di konsol Google Cloud, buka halaman Topics.

    Buka Topik

  2. Klik topik impor masing-masing yang Anda gunakan (topik impor Cloud Storage, topik impor Azure Event Hubs, topik impor Amazon MSK, atau topik impor Confluent Cloud).

  3. Di halaman detail topik, klik Edit.

  4. Hapus centang Aktifkan log platform.

  5. Klik Perbarui.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Untuk menonaktifkan log platform, pastikan tingkat keparahan log penyerapan ditetapkan ke DISABLED. Jalankan perintah gcloud pubsub topics update dengan semua kemungkinan flag yang menentukan setelan untuk masing-masing topik yang Anda gunakan:

    Misalnya, untuk menonaktifkan log di topik impor Cloud Storage yang ada, sertakan flag --ingestion-log-severity=DISABLED dalam perintah gcloud pubsub topics update dan sertakan semua kemungkinan flag yang menentukan setelan untuk topik impor Cloud Storage.

    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

Melihat log platform

Untuk melihat log platform untuk masing-masing topik impor yang Anda gunakan, 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. Klik tombol Show query.

  5. Untuk memfilter log agar hanya menampilkan entri untuk topik impor masing-masing yang Anda gunakan (topik impor Cloud Storage, topik impor Azure Event Hubs, topik impor Amazon MSK, atau topik impor Confluent Cloud), ketik resource.type="resource.type=pubsub_topic AND severity=WARNING" ke kolom kueri, lalu klik Jalankan kueri.

  6. 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 masing-masing topik impor yang Anda gunakan, gunakan perintah gcloud logging read.

Tentukan filter untuk membatasi hasil ke log platform untuk masing-masing topik impor yang Anda gunakan (topik impor Cloud Storage, topik impor Azure Event Hubs, topik impor Amazon MSK, atau topik impor Confluent Cloud).

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.

Cloud Storage

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/my-project/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": "my-project",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/my-project/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 Google Cloud Project ID.
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/my-project/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": "my-project"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/my-project/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 Google Cloud project ID.
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 Cloud Logging.

Amazon MSK

Pelanggaran API 

  {
  "insertId": "k3breb2q",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "awsMskFailure": {
      "apiViolationReason": {},
      "clusterArn": "arn:aws:kafka:us-east-1:291552718126:cluster/cluster-ingestion/abb9faea-4070-4eb76-9c21-f98abca92eaf-2",
      "kafkaTopic": "msk-topic",
      "partitionId": "1",
      "offset": "11"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/msk-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "msk-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T16:18:16.241643258Z"
}
Kolom log Deskripsi
insertId ID unik untuk entri log.
jsonPayload.@type Mengidentifikasi jenis peristiwa. Selalu type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.awsMskFailure.clusterArn ARN cluster topik yang ditransfer.
jsonPayload.awsMskFailure.kafkaTopic Nama topik Kafka yang ditransfer.
jsonPayload.awsMskFailure.partitionId ID partisi yang berisi pesan yang gagal diserap.
jsonPayload.awsMskFailure.offset Offset dalam partisi pesan yang gagal diserap.
jsonPayload.awsMskFailure.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 Google Cloud project ID.
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 Cloud Logging.

Azure Event Hubs

Pelanggaran API 

{
  "insertId": "i1fbqnb12",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "azureEventHubsFailure": {
      "apiViolationReason": {},
      "namespace": "my-namespace",
      "eventHub": "my-event-hub",
      "partitionId": "1",
      "offset": "15"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/event-hubs-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "event-hubs-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T14:05:12.338211450Z"
}
Kolom log Deskripsi
insertId ID unik untuk entri log.
jsonPayload.@type Mengidentifikasi jenis peristiwa. Selalu type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.azureEventHubsFailure.namespace Namespace yang berisi event hub yang ditransfer.
jsonPayload.azureEventHubsFailure.eventHub Nama hub peristiwa tempat peristiwa ditransfer.
jsonPayload.azureEventHubsFailure.partitionId ID partisi yang berisi pesan yang gagal diserap.
jsonPayload.azureEventHubsFailure.offset Offset dalam partisi pesan yang gagal diserap.
jsonPayload.azureEventHubsFailure.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 Google Cloud project ID.
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 Cloud Logging.

Confluent Cloud

Kegagalan teks 

{
  "insertId": "i1fbqnb14",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "confluentCloudFailure": {
      "apiViolationReason": {},
      "clusterId": "lma-1x18ae",
      "kafkaTopic": "confluent-topic",
      "partitionId": "1",
      "offset": "19"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/confluent-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "confluent-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T17:03:11.428221440Z"
}
Kolom log Deskripsi
insertId ID unik untuk entri log.
jsonPayload.@type Mengidentifikasi jenis peristiwa. Selalu type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.confluentCloudFailure.clusterId ID cluster yang berisi topik yang ditransfer.
jsonPayload.confluentCloudFailure.kafkaTopic Nama topik Kafka yang ditransfer.
jsonPayload.confluentCloudFailure.partitionId ID partisi yang berisi pesan yang gagal diserap.
jsonPayload.confluentCloudFailure.offset Offset dalam partisi pesan yang gagal diserap.
jsonPayload.confluentCloudFailure.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 Cloud Logging.
Apache Kafka® adalah merek dagang terdaftar dari Apache Software Foundation atau afiliasinya di Amerika Serikat dan/atau negara lainnya.