Menggunakan log platform untuk memecahkan masalah topik impor

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

Tentang log platform

Layanan yang didukung Google Cloud membuat kumpulan log platformnya sendiri, yang mencatat 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) (roles/logging.viewer) Pelihat Log. Untuk mengetahui informasi selengkapnya tentang akses Logging, lihat Kontrol akses dengan IAM.

Berikut cara memverifikasi dan memberikan akses IAM:

Tentang kegagalan penyerapan topik impor

Topik impor dapat mengalami masalah yang mencegah data berhasil diproses.

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 memproses objek Cloud Storage atau sebagian objek.

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

  • Ukuran pesan

    • Ukuran masing-masing pesan tidak boleh lebih dari 10 MB. Jika ya, 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 diproses.

    • 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 mengetahui 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 mencegah pesan diproses.

  • Format data

Topik impor 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 di-ingest.

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

  • Ukuran pesan

    • Ukuran masing-masing pesan tidak boleh lebih dari 10 MB. Jika ya, seluruh pesan akan dilewati.

  • Atribut pesan

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

    • 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 mengetahui 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 mengetahui 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 disetel ke WARNING atau tingkat keparahan yang lebih rendah seperti INFO atau DEBUG. Jalankan perintah gcloud pubsub topics create untuk topik yang Anda gunakan:

    Misalnya, untuk mengaktifkan log platform di topik impor Cloud Storage, sertakan flag --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 yang sesuai 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 ingestion-log-severity ditetapkan ke WARNING atau tingkat keparahan yang lebih rendah seperti INFO atau DEBUG. Jalankan perintah gcloud pubsub topics update dengan semua kemungkinan tanda yang menentukan setelan untuk topik yang Anda gunakan:

    Misalnya, untuk memperbarui log pada topik impor Cloud Storage yang ada, sertakan flag --ingestion-log-severity=WARNING dalam perintah gcloud pubsub topics create dan sertakan semua kemungkinan nilai 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=WARNING

Menonaktifkan log platform

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

Konsol

  1. Di konsol Google Cloud , buka halaman Topics.

    Buka Topik

  2. Klik topik impor yang sesuai 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 ingestion-log-severity disetel ke DISABLED. Jalankan perintah gcloud pubsub topics update dengan semua kemungkinan tanda yang menentukan setelan untuk topik yang Anda gunakan:

    Misalnya, untuk menonaktifkan log pada 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 topik impor yang Anda gunakan, lakukan hal berikut:

Google Cloud console

  1. Di konsol Google Cloud , buka Logs Explorer.

    Buka Logs Explorer

  2. Pilih project Google Cloud .

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

  4. Klik tombol Tampilkan kueri.

  5. Untuk memfilter log Anda 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 dalam kolom kueri, lalu klik Jalankan kueri.

  6. Di panel Query results, klik Edit time untuk mengubah jangka waktu yang akan ditampilkan hasilnya.

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

Tentukan filter untuk membatasi hasil Anda ke log platform 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).

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 parsing Avro yang lebih spesifik. Kolom ini dibiarkan kosong.
jsonPayload.topic Topik Pub/Sub yang dituju oleh 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 tempat topik diserap.
jsonPayload.awsMskFailure.kafkaTopic Nama topik Kafka yang sedang di-ingest dari.
jsonPayload.awsMskFailure.partitionId ID partisi yang berisi pesan yang gagal di-ingest.
jsonPayload.awsMskFailure.offset Offset dalam partisi pesan yang gagal diproses.
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 hub peristiwa yang sedang di-ingest.
jsonPayload.azureEventHubsFailure.eventHub Nama hub peristiwa yang data sedang di-ingest dari hub tersebut.
jsonPayload.azureEventHubsFailure.partitionId ID partisi yang berisi pesan yang gagal di-ingest.
jsonPayload.azureEventHubsFailure.offset Offset dalam partisi pesan yang gagal diproses.
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 sedang di-ingest dari.
jsonPayload.confluentCloudFailure.kafkaTopic Nama topik Kafka yang sedang di-ingest dari.
jsonPayload.confluentCloudFailure.partitionId ID partisi yang berisi pesan yang gagal di-ingest.
jsonPayload.confluentCloudFailure.offset Offset dalam partisi pesan yang gagal diproses.
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 The Apache Software Foundation atau afiliasinya di Amerika Serikat dan/atau negara lain.