Memecahkan Masalah Template Flex

Halaman ini memberikan tips pemecahan masalah dan strategi penelusuran bug yang mungkin berguna jika Anda menggunakan Template Flex Dataflow. Informasi ini dapat membantu Anda mendeteksi waktu tunggu polling habis, menentukan alasan di balik habisnya waktu tunggu, dan memperbaiki masalah.

Memecahkan masalah waktu tunggu polling

Bagian ini memberikan langkah-langkah untuk mengidentifikasi penyebab waktu tunggu polling habis.

Waktu tunggu polling

Tugas Template Flex Anda mungkin menampilkan pesan error berikut:

Timeout in polling result file: ${file_path}.
Service account: ${service_account_email}
Image URL: ${image_url}
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling

Error ini dapat terjadi karena alasan berikut:

1. Image Docker dasar diganti.
2. Akun layanan yang mengisi ${service_account_email} tidak memiliki beberapa izin yang diperlukan.
3. Alamat IP eksternal dinonaktifkan, dan VM tidak dapat terhubung ke kumpulan alamat IP eksternal yang digunakan oleh Google API dan layanan Google.
4. Program yang membuat grafik memerlukan waktu terlalu lama untuk diselesaikan.
5. Opsi pipeline sedang diganti.
6. (Khusus Python) Ada masalah dengan file requirements.txt.
7. Terjadi error sementara.

Untuk mengatasi masalah ini, periksa terlebih dahulu error sementara dengan memeriksa log tugas dan mencoba lagi. Jika langkah-langkah tersebut tidak menyelesaikan masalah, coba langkah-langkah pemecahan masalah berikut.

Verifikasi titik entri Docker

Coba langkah ini jika Anda menjalankan template dari image Docker kustom, bukan menggunakan salah satu template yang disediakan.

Periksa titik entri container menggunakan perintah berikut:

docker inspect $TEMPLATE_IMAGE

Output berikut diharapkan:

Jika Anda mendapatkan output yang berbeda, berarti titik entri penampung Docker Anda diganti. Pulihkan $TEMPLATE_IMAGE ke default.

Memeriksa izin akun layanan

Pastikan akun layanan yang disebutkan dalam pesan memiliki izin berikut:

• Fungsi ini harus dapat membaca dan menulis jalur Cloud Storage yang mengisi ${file_path} dalam pesan.
• Aplikasi harus dapat membaca image Docker yang mengisi ${image_url} dalam pesan.

Mengonfigurasi Akses Google Pribadi

Jika alamat IP eksternal dinonaktifkan, Anda harus mengizinkan VM Compute Engine untuk terhubung ke kumpulan alamat IP eksternal yang digunakan oleh Google API dan layanan Google. Aktifkan Akses Google Pribadi di subnet yang digunakan oleh antarmuka jaringan VM.

Untuk mengetahui detail konfigurasi, lihat Mengonfigurasi Akses Google Pribadi.

Secara default, jika VM Compute Engine tidak memiliki alamat IP eksternal yang ditetapkan ke antarmuka jaringan, VM tersebut hanya dapat mengirim paket ke tujuan alamat IP internal lainnya.

Periksa apakah program peluncur gagal keluar

Program yang membuat pipeline harus selesai sebelum pipeline dapat diluncurkan. Error polling dapat menunjukkan bahwa polling memerlukan waktu terlalu lama.

Beberapa hal yang dapat Anda lakukan untuk menemukan penyebab dalam kode adalah:

• Periksa log tugas dan lihat apakah ada operasi yang tampaknya membutuhkan waktu lama untuk diselesaikan. Contohnya adalah permintaan untuk resource eksternal.
• Pastikan tidak ada thread yang menghalangi program keluar. Beberapa klien mungkin membuat thread mereka sendiri, dan jika klien ini tidak dihentikan, program akan menunggu selamanya hingga thread ini bergabung.

Pipeline yang diluncurkan secara langsung yang tidak menggunakan template tidak memiliki batasan ini. Oleh karena itu, jika pipeline berfungsi secara langsung, tetapi tidak sebagai template, maka penggunaan template mungkin menjadi penyebab utamanya. Menemukan masalah dalam template dan memperbaikinya dapat menyelesaikan masalah ini.

Memverifikasi apakah opsi pipeline yang diperlukan disembunyikan

Saat menggunakan Template Flex, Anda dapat mengonfigurasi beberapa opsi pipeline, tetapi tidak semua opsi pipeline selama inisialisasi pipeline. Untuk mengetahui informasi selengkapnya, lihat bagian Gagal membaca file tugas dalam dokumen ini.

Hapus Apache Beam dari file persyaratan (Khusus Python)

Jika Dockerfile Anda menyertakan requirements.txt dengan apache-beam[gcp], hapus dari file dan instal secara terpisah. Perintah berikut menunjukkan cara menyelesaikan langkah ini:

RUN pip install apache-beam[gcp]
RUN pip install -U -r ./requirements.txt

Menempatkan Apache Beam dalam file persyaratan dapat menyebabkan waktu peluncuran yang lama, yang sering kali mengakibatkan waktu tunggu habis.

Waktu tunggu polling saat menggunakan Python

Jika Anda menjalankan tugas Dataflow menggunakan Template Fleksibel dan Python, tugas Anda mungkin diantrekan selama beberapa waktu, gagal dijalankan, lalu menampilkan error berikut:

Timeout in polling

File requirements.txt yang digunakan untuk menginstal dependensi yang diperlukan menyebabkan error. Saat Anda meluncurkan tugas Dataflow, semua dependensi akan di-stage terlebih dahulu agar file ini dapat diakses oleh VM pekerja. Proses ini melibatkan pendownloadan dan kompilasi setiap dependensi langsung dan tidak langsung dalam file requirements.txt. Beberapa dependensi mungkin memerlukan waktu beberapa menit untuk dikompilasi. Terutama PyArrow mungkin memerlukan waktu untuk dikompilasi. PyArrow adalah dependensi tidak langsung yang digunakan oleh Apache Beam dan sebagian besar Library Klien Cloud.

Untuk mengoptimalkan performa tugas, gunakan Dockerfile atau container kustom untuk memaketkan dependensi terlebih dahulu. Untuk mengetahui informasi selengkapnya, lihat Dependensi paket di "Mengonfigurasi Template Flex".

Kegagalan peluncuran tugas

Bagian berikut berisi error umum yang menyebabkan kegagalan peluncuran tugas dan langkah-langkah untuk menyelesaikan atau memecahkan masalah error.

Masalah startup awal

Jika proses peluncuran template gagal pada tahap awal, log Flex Template reguler mungkin tidak tersedia. Untuk menyelidiki masalah startup, aktifkan logging port serial untuk VM peluncur template.

Untuk mengaktifkan logging untuk template Java, tetapkan opsi enableLauncherVmSerialPortLogging ke true. Untuk mengaktifkan logging untuk template Python dan Go, tetapkan opsi enable_launcher_vm_serial_port_logging ke true. Di konsol Google Cloud , parameter ini tercantum di Optional parameters sebagai Enable Launcher VM Serial Port Logging.

Anda dapat melihat log output port serial VM peluncur template di Cloud Logging. Untuk menemukan log VM peluncur tertentu, gunakan kueri resource.type="gce_instance" "launcher-number" dengan number dimulai dengan tanggal saat ini dalam format YYYMMDD.

Kebijakan organisasi Anda mungkin melarang Anda mengaktifkan logging output port serial.

Gagal membaca file tugas

Saat Anda mencoba menjalankan tugas dari Template Flex, tugas Anda mungkin gagal dengan error berikut:

Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object with error message: ...: Unable to open template file

Error ini terjadi saat opsi inisialisasi pipeline yang diperlukan ditimpa. Saat menggunakan Template Flex, Anda dapat mengonfigurasi beberapa opsi pipeline, tetapi tidak semua opsi pipeline selama inisialisasi pipeline. Jika argumen command line yang diperlukan oleh Template Flex ditimpa, tugas dapat mengabaikan, mengganti, atau membuang opsi pipeline yang diteruskan oleh peluncur template. Tugas mungkin gagal diluncurkan, atau tugas yang tidak menggunakan Template Fleksibel mungkin diluncurkan.

Untuk menghindari masalah ini, selama inisialisasi pipeline, jangan ubah opsi pipeline berikut dalam kode pengguna atau dalam file metadata.json:

Gagal membaca file hasil

Saat Anda mencoba menjalankan tugas dari Template Flex, tugas Anda mungkin gagal dengan error berikut:

Failed to read the result file : gs://BUCKET_NAME with error message: (ERROR_NUMBER): Unable to open template file: gs://BUCKET_NAME

Error ini terjadi saat akun layanan default Compute Engine tidak memiliki semua izin yang diperlukan untuk menjalankan Template Fleksibel. Untuk daftar izin yang diperlukan, lihat Izin untuk menjalankan Template Fleksibel.

Izin ditolak pada resource

Saat Anda mencoba menjalankan tugas dari Template Flex, tugas Anda mungkin gagal dengan error berikut:

Permission "MISSING_PERMISSION" denied on resource "projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME" (or it may not exist).

Error ini terjadi saat akun layanan yang digunakan tidak memiliki izin untuk mengakses resource yang diperlukan untuk menjalankan Template Fleksibel.

Untuk menghindari masalah ini, pastikan akun layanan memiliki izin yang diperlukan. Sesuaikan izin akun layanan sesuai kebutuhan.

Flag disediakan, tetapi tidak ditentukan

Saat Anda mencoba menjalankan Template Flex Go dengan opsi pipeline worker_machine_type, pipeline gagal dengan error berikut:

flag provided but not defined: -machine_type

Error ini disebabkan oleh masalah umum di Apache Beam Go SDK versi 2.47.0 dan yang lebih lama. Untuk mengatasi masalah ini, upgrade ke Apache Beam Go versi 2.48.0 atau yang lebih baru.

Tidak dapat mengambil JAR server tugas jarak jauh

Jika Anda mencoba menjalankan tugas dari Template Fleksibel saat Anda tidak terhubung ke internet, tugas Anda mungkin gagal dengan error berikut:

Unable to fetch remote job server jar at
https://repo.maven.apache.org/maven2/org/apache/beam/beam-sdks-java-io-expansion-service/VERSION/beam-sdks-java-io-expansion-service-VERSION.jar:
\u003curlopen error [Errno 101] Network is unreachable\u003e

Error ini terjadi karena VM tidak dapat mendownload paket Java Apache Beam dari internet. Paket ini diperlukan saat Anda menjalankan tugas multi-bahasa menggunakan Template Flex.

Untuk mengatasi masalah ini, lakukan salah satu perubahan berikut:

• Hubungkan ke internet. Saat terhubung ke internet, tugas Anda dapat mengakses file yang diperlukan.

• Sertakan paket Java Apache Beam di direktori lokal Anda agar tugas Anda dapat mengaksesnya secara lokal. Letakkan file di direktori berikut: /root/.apache_beam/cache/jars/. Contoh, /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar.

Tidak dapat memperoleh sistem file dari jalur yang ditentukan

Saat Anda mencoba menjalankan tugas dari Template Flex, tugas Anda mungkin gagal dengan error berikut:

ValueError: Unable to get filesystem from specified path, please use
the correct path or ensure the required dependency is installed, e.g., pip
install apache-beam[gcp]. Path specified: PATH

Error ini terjadi saat tugas menggunakan image container Flex Template, dan image container tidak berisi penginstalan Java.

Untuk mengatasi masalah ini, tambahkan baris berikut ke Dockerfile Anda:

sh RUN apt-get update && apt-get install -y openjdk-17-jdk

Perintah ini akan menginstal Java di lingkungan container Anda.

Penundaan peluncuran Template Flex

Saat Anda mengirimkan tugas Template Flex, permintaan tugas akan masuk ke antrean Spanner. Peluncur template mengambil tugas dari antrean Spanner, lalu menjalankan template. Jika Spanner memiliki backlog pesan, penundaan yang signifikan mungkin terjadi antara waktu Anda mengirimkan tugas dan waktu tugas diluncurkan.

Untuk mengatasi masalah ini, luncurkan Template Fleksibel dari region lain.

Parameter template tidak valid

Saat Anda mencoba menggunakan gcloud CLI untuk menjalankan tugas yang menggunakan template yang disediakan Google, error berikut akan terjadi:

ERROR: (gcloud.beta.dataflow.flex-template.run) INVALID_ARGUMENT: The template
parameters are invalid. Details: defaultSdkHarnessLogLevel: Unrecognized
parameter defaultWorkerLogLevel: Unrecognized parameter

Error ini terjadi karena beberapa template yang disediakan Google tidak mendukung opsi defaultSdkHarnessLog dan defaultWorkerLog.

Sebagai solusinya, salin file spesifikasi template ke bucket Cloud Storage. Tambahkan parameter tambahan berikut ke file.

"metadata": {
    ...
    "parameters": [
      ...,
      {
        "name": "defaultSdkHarnessLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      },
      {
        "name": "defaultWorkerLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      }
    ]
  }

Setelah Anda membuat perubahan ini pada file template, gunakan perintah berikut untuk menjalankan template.

--template-file-gcs-location=gs://BUCKET_NAME/FILENAME

Ganti nilai berikut:

• BUCKET_NAME: nama bucket Cloud Storage Anda
• FILENAME: nama file spesifikasi template Anda

Log peluncur Template Flex menampilkan tingkat keparahan yang salah

Jika peluncuran Template Flex kustom gagal, pesan berikut akan muncul di file log dengan tingkat keparahan ERROR:

ERROR: Error occurred in the launcher container: Template launch failed. See console logs.

Penyebab utama kegagalan peluncuran biasanya muncul di log sebelum pesan ini dengan tingkat keparahan INFO. Meskipun tingkat log ini mungkin salah, hal ini sudah diperkirakan, karena peluncur template Flex tidak dapat mengekstrak detail tingkat keparahan dari pesan log yang dihasilkan oleh aplikasi Apache Beam.

Jika Anda ingin melihat tingkat keparahan yang benar untuk setiap pesan di log peluncur, konfigurasi template Anda untuk membuat log dalam format JSON, bukan dalam teks biasa. Konfigurasi ini memungkinkan peluncur template mengekstrak tingkat keparahan pesan log yang benar. Gunakan struktur pesan berikut:

{
  "message": "The original log message",
  "severity": "DEBUG/INFO/WARN/ERROR"
}

Di Java, Anda dapat menggunakan logger Logback dengan implementasi appender JSON kustom. Untuk mengetahui informasi selengkapnya, lihat contoh konfigurasi Logback dan contoh kode appender JSON di GitHub.

Masalah ini hanya memengaruhi log yang dihasilkan oleh peluncur Template Flex saat pipeline diluncurkan. Saat peluncuran berhasil dan pipeline berjalan, log yang dihasilkan oleh pekerja Dataflow memiliki tingkat keparahan yang tepat.

Template yang disediakan Google menampilkan tingkat keparahan yang benar selama peluncuran tugas, karena template yang disediakan Google menggunakan pendekatan logging JSON ini.