Memecahkan Masalah Template Flex

Halaman ini memberikan tips pemecahan masalah dan strategi proses debug yang mungkin berguna jika Anda menggunakan Template Flex Dataflow. Secara default, proses peluncuran Template Flex memiliki waktu tunggu 12 menit. Proses peluncuran ini mencakup pengambilan image container template dan menjalankan kode untuk membuat grafik tugas. Jika peluncuran tidak selesai dalam jangka waktu 12 menit ini, tugas akan gagal dengan error "Timeout in polling result file". Informasi ini dapat membantu Anda mendeteksi waktu tunggu polling, menentukan alasan di balik waktu tunggu habis, dan memperbaiki masalah.

Error waktu tunggu polling

Tugas Anda mungkin menampilkan salah satu pesan error berikut:

Timeout in polling result file: FILE_PATH. Possible causes are:
1. Your launch takes too long time to finish. Please check the logs on stackdriver.
2. Service account SERVICE_ACCOUNT may not have enough permissions to pull
container image IMAGE_PATH or create new objects in FILE_PATH.
3. Transient errors occurred, please try again.

Timeout in polling result file: FILE_PATH.
Service account: SERVICE_ACCOUNT
Image URL: IMAGE_PATH
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 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. VM peluncur tidak dapat me-resolve atau mengakses gcr.io.
  5. Image container Template Flex yang besar.
  6. Program yang membuat grafik memerlukan waktu terlalu lama untuk selesai.
  7. Kode yang berjalan di VM peluncur memerlukan waktu terlalu lama untuk selesai.
  8. Error jaringan atau Cloud Storage yang tidak konsisten.
  9. Opsi pipeline ditimpa.
  10. Pengguna Python: Menginstal atau melakukan staging dependensi memerlukan waktu terlalu lama.
  11. Terjadi error sementara.

Untuk mengatasi masalah ini, periksa terlebih dahulu error sementara dengan memeriksa log tugas dan mencoba lagi.

Ikuti panduan di bagian Masalah startup awal untuk mengaktifkan logging port serial, yang mungkin mengungkapkan informasi tambahan.

Jika langkah-langkah tersebut tidak mengatasi masalah, coba langkah-langkah pemecahan masalah berikut.

Opsional: Jalankan template untuk mendiagnosis masalah Anda lebih lanjut

Untuk mengidentifikasi lebih lanjut alasan sebelumnya yang mungkin menyebabkan error ini, gunakan strategi berikut:

  1. Jalankan template WordCount yang disediakan Google. Pastikan untuk memberikan parameter yang unik untuk kasus penggunaan Anda, seperti subnetwork dari project VPC Bersama, IP pribadi untuk VM pekerja, dan akun layanan pekerja Dataflow yang ingin Anda gunakan. Untuk mengetahui informasi selengkapnya tentang cara memberikan parameter ini, lihat Referensi gcloud dan Referensi API.

    Jika Anda dapat menyelesaikan tugas ini dengan sukses, hal ini menunjukkan bahwa Jaringan, Izin IAM, dan Akses Google Pribadi kemungkinan dikonfigurasi dengan benar.

  2. Selesaikan Panduan memulai menjalankan pipeline menggunakan builder tugas cepat, yang menjalankan tugas sebagai Template Flex. Jika tugas Anda gagal sebelum meluncurkan VM pekerja, akses VM peluncur dan coba download contoh image Docker menggunakan perintah yang mirip dengan berikut:

    docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-template

    Jika perintah ini gagal, mungkin ada masalah jaringan saat mendownload image. Dalam hal ini, hubungi tim jaringan internal Anda.

  3. Jalankan Template Flex yang disediakan Google dan periksa hasilnya. Jika tugas template yang disediakan Google berhasil diselesaikan, hal ini menunjukkan bahwa masalah tersebut kemungkinan terkait dengan file kode template kustom tertentu. Dalam hal ini, Anda harus terus memecahkan masalah kode tertentu untuk mengatasi masalah tersebut.

Memverifikasi 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:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

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

Memeriksa izin akun layanan

Pastikan akun layanan yang disebutkan dalam pesan memiliki izin berikut:

  • Akun layanan harus dapat membaca dan menulis jalur Cloud Storage yang mengisi ${file_path} dalam pesan.
  • Akun layanan 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 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.

Masalah akses GCR.io

VM peluncur Template Flex memerlukan akses ke gcr.io untuk mengambil container agen logging (gcr.io/dataflow-templates-base/template-launcher-logger-distroless). Agen ini bertanggung jawab untuk melakukan streaming log peluncur ke Cloud Logging. Jika VM peluncur tidak dapat me-resolve atau terhubung ke gcr.io, proses startup mungkin berhenti merespons, sehingga menyebabkan waktu tunggu polling habis.

Masalah ini dapat terjadi meskipun image template kustom Anda disimpan di Artifact Registry, karena agen logging selalu diambil dari gcr.io.

Untuk mendiagnosis dan mengatasi masalah ini:

  1. Aktifkan logging port serial: Ikuti langkah-langkah di bagian Masalah startup awal. Jika Anda melihat bahwa proses cloud-init macet atau jika ada error terkait gcr-wait-online.service, kemungkinan ada masalah DNS atau jaringan.

  2. SSH ke VM peluncur: Gunakan perintah gcloud compute ssh untuk terhubung ke VM peluncur saat masih berjalan:

    gcloud compute ssh launcher-JOB_ID --tunnel-through-iap

    Ganti JOB_ID dengan ID tugas Dataflow Anda.

  3. Verifikasi resolusi DNS: Jalankan perintah berikut di dalam peluncur VM:

    curl -I https://gcr.io

    Jika perintah gagal dengan error "Could not resolve host", konfigurasi DNS Anda tidak memiliki entri untuk gcr.io.

  4. Periksa layanan startup yang macet: Periksa log output cloud-init:

    sudo cat /var/log/cloud-init-output.log

    Cari pesan yang menunjukkan bahwa proses menunggu jaringan atau gcr.io dapat diakses.

Selain itu, pastikan setelan DNS VPC Anda mengizinkan resolusi gcr.io. Dalam beberapa konfigurasi jaringan pribadi, Anda mungkin perlu menambahkan data DNS A tertentu untuk gcr.io yang mengarah ke rentang IP Google API Terbatas atau Google API Pribadi.

Image container besar

Jika image container Template Flex Anda besar, pengambilan dan peluncuran template dapat melebihi waktu tunggu default 12 menit sehingga menyebabkan kegagalan tugas.

Untuk mengurangi masalah ini, coba strategi berikut :

  • Optimalkan image Anda untuk mengurangi ukurannya guna mempercepat proses pengambilan.
  • Gunakan flag --launcher-machine-type untuk memilih jenis mesin dengan lebih banyak core CPU, yang membantu mengambil image lebih cepat dan menghasilkan peluncuran yang lebih cepat.
  • Gunakan flag --launcher-vm-timeout-secs untuk menentukan durasi waktu tunggu yang lebih lama untuk VM peluncur, sehingga dapat melampaui batas default 12 menit.

Memeriksa apakah program peluncur gagal keluar

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

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

  • Pastikan tidak ada thread yang memblokir program agar tidak keluar. Beberapa klien mungkin membuat thread mereka sendiri, dan jika klien ini tidak dimatikan, program akan menunggu selamanya agar thread ini bergabung.
  • Dalam kode yang menentukan pipeline Anda, jangan gunakan waitUntilFinish (untuk Java) atau wait_until_finish (untuk Python). Fungsi ini memblokir program agar tidak keluar, yang mencegah Template Flex meluncurkan pipeline.

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, penggunaan template mungkin menjadi penyebab utamanya. Menemukan masalah dalam template dan memperbaiki template dapat mengatasi masalah tersebut.

Kode yang berjalan lama di VM peluncur

Jika kode dalam program utama Anda memerlukan waktu terlalu lama untuk dieksekusi, Template Flex mungkin mengalami waktu tunggu habis sebelum pipeline diluncurkan. Hal ini dapat terjadi jika kode melakukan komputasi yang kompleks atau melakukan panggilan sinkron ke resource eksternal selama inisialisasi.

Untuk mendiagnosis masalah ini, periksa log tugas untuk mengetahui operasi yang memerlukan waktu lama untuk diselesaikan. Contohnya mencakup permintaan untuk resource eksternal, pencarian data besar, atau logika inisialisasi berat yang dapat Anda pindahkan ke fase eksekusi pipeline.

Error jaringan atau Cloud Storage yang tidak konsisten

Error "Timeout in polling result file" atau "Failed to read the result file" yang tidak konsisten dapat terjadi karena latensi jaringan yang tinggi atau masalah sementara dengan Cloud Storage API. Persaingan jaringan kronis di VPC Anda, khususnya dalam jalur Akses Google Pribadi, sering kali menyebabkan latensi 400–500 md.

"Timeout in polling result file" biasanya merupakan kegagalan yang lambat, sedangkan "Failed to read the result file" adalah kegagalan yang cepat, tetapi keduanya sering kali menunjukkan masalah konektivitas yang sama.

Untuk mendiagnosis kegagalan yang tidak konsisten ini:

  1. Periksa latensi jaringan: Pantau latensi jaringan dalam VPC Anda. Latensi tinggi yang berkelanjutan dapat menyebabkan waktu tunggu habis saat VM peluncur mencoba menulis atau membaca file hasil tugas dari Cloud Storage.

  2. Pantau metrik Cloud Storage API:

    1. Di Google Cloud konsol, buka dasbor APIs & Services.

      Buka API &layanan yang diaktifkan

    2. Filter dan pilih Cloud Storage API.

    3. Tinjau diagram untuk Traffic (byte yang dikirim dan diterima) dan Error rate.

    4. Cari lonjakan di 5xx errors (seperti error 503) yang sesuai dengan waktu persis kegagalan tugas.

Jika Anda mengidentifikasi lonjakan error atau latensi tinggi, selidiki performa jaringan VPC Anda atau hubungiDukungan Pelanggan Cloud untuk mendapatkan bantuan terkait potensi gangguan layanan.

Memeriksa apakah opsi pipeline yang diperlukan disembunyikan

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

Pengguna Python: Pengelolaan dependensi

Jika Anda menjalankan tugas Template Flex Python yang menyediakan dependensi tambahan dalam file requirements.txt, tugas Anda mungkin gagal diluncurkan. Kegagalan ini terjadi saat mendownload atau menginstal dependensi yang ditentukan dalam file persyaratan memerlukan waktu lebih lama daripada waktu yang dialokasikan untuk meluncurkan template Flex.

Untuk mengoptimalkan performa tugas, kemas dependensi terlebih dahulu saat membuat template untuk menghindari keharusan mendownload atau menginstal dependensi selama peluncuran template. Untuk mengetahui informasi selengkapnya, lihat bagian Mengemas dependensi untuk Python di "Mengonfigurasi Template Flex".

Kegagalan peluncuran tugas

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

Masalah startup awal

Jika proses peluncuran template gagal pada tahap awal, log Template Flex 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 Google Cloud konsol, 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 untuk 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...

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

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

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

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...

Error ini terjadi saat akun layanan default Compute Engine tidak memiliki semua izin yang diperlukan untuk menjalankan Template Flex.

Untuk mengetahui daftar izin yang diperlukan, lihat Izin untuk menjalankan Template Flex.

Error ini juga dapat disebabkan oleh latensi jaringan yang tidak konsisten atau masalah Cloud Storage API. Untuk mengetahui informasi selengkapnya, lihat Error jaringan atau Cloud Storage yang tidak konsisten.

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 Flex.

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 akan 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 Flex saat 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 Apache Beam Java dari internet. Paket ini diperlukan saat Anda menjalankan tugas multi-bahasa menggunakan Template Flex.

Untuk mengatasi masalah ini, lakukan salah satu perubahan berikut:

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

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

Tidak dapat mendapatkan 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 Template Flex, 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 menginstal Java di lingkungan container Anda.

Kehabisan resource VM peluncur

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

Failed to start the VM, launcher-ID, used for launching because of status code: INTERNAL, reason: Unknown error in operation 'OPERATION_ID': [ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS] 'The zone 'projects/PROJECT_ID/zones/ZONE_ID' does not have enough resources available to fulfill the request.

Nama VM launcher-ID mewakili nama VM peluncur. VM peluncur bertanggung jawab untuk mengumpulkan resource tugas, seperti kode dan image template, sebelum membuat dan mengirimkan grafik tugas ke layanan Dataflow untuk memulai pekerjaan.

Jika Anda tidak menentukan parameter launcherMachineType, Dataflow akan memilih jenis mesin default untuk VM peluncur. Pilihan ini tidak bergantung pada machineType pekerja. Error kehabisan resource dapat terjadi jika jenis mesin default ini tidak tersedia di region atau zona tugas.

Untuk mengatasi masalah ini, gunakan salah satu strategi berikut:

Penundaan peluncur 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 Flex Anda dari region lain.

Parameter template tidak valid

Saat Anda mencoba menggunakan gcloud CLI untuk menjalankan tugas yang menggunakan a 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 melakukan 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 dalam 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 dalam log sebelum pesan ini dengan tingkat keparahan INFO. Meskipun tingkat log ini mungkin salah, hal ini diharapkan, karena peluncur template Flex tidak memiliki cara untuk mengekstrak detail tingkat keparahan dari pesan log yang dihasilkan oleh aplikasi Apache Beam.

Jika Anda ingin melihat tingkat keparahan yang benar untuk setiap pesan dalam log peluncur, konfigurasi template Anda untuk menghasilkan 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 konfigurasi contoh Logback dan kode contoh 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.