Memecahkan Masalah Template Flex

Halaman ini memberikan tips pemecahan masalah dan strategi proses debug yang mungkin berguna jika Anda menggunakan Template Fleksibel Dataflow. Secara default, proses peluncuran Template Flex memiliki waktu tunggu 12 menit. Proses peluncuran ini mencakup pengambilan image container template dan mengeksekusi 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, dan memperbaiki masalah.

Terjadi error saat memuat daftar template di konsol Google Cloud

Di konsol Google Cloud , saat Anda mencoba melihat daftar template di halaman Create job from template Dataflow, Anda akan melihat error yang mirip dengan berikut ini:

Error retrieving templates. Custom templates can still be used.

Jika organisasi Anda menggunakan kebijakan principal access boundary (PAB), principal (seperti pengguna atau akun layanan) mungkin diblokir agar tidak dapat melihat dan menjalankan template yang disediakan Google. Untuk mengatasi masalah ini, coba panduan di Mengakses template yang disediakan Google dengan kebijakan batas akses utama.

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 telah 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 terputus-putus.
  9. Opsi pipeline sedang ditimpa.
  10. Pengguna Python: Menginstal atau melakukan staging dependensi memerlukan waktu terlalu lama.
  11. Terjadi error sementara.

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

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

Jika langkah-langkah tersebut tidak menyelesaikan 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 worker VM, dan akun layanan worker 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 berhasil, hal ini menunjukkan bahwa Jaringan, Izin IAM, dan Akses Google Pribadi kemungkinan telah dikonfigurasi dengan benar.

  2. Selesaikan panduan memulai Menjalankan pipeline menggunakan pembuat tugas, yang menjalankan tugas sebagai Template Flex. Jika tugas Anda gagal sebelum meluncurkan worker VM, akses launcher VM 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 masalahnya kemungkinan terkait dengan file kode template kustom spesifik Anda. Dalam hal ini, Anda harus melanjutkan pemecahan masalah kode tertentu untuk menyelesaikan masalah.

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 akan muncul:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

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

Memeriksa izin akun layanan

Pastikan akun layanan yang disebutkan dalam pesan memiliki izin berikut:

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

Untuk mendiagnosis dan menyelesaikan 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 VM peluncur:

    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 sedang menunggu jaringan atau gcr.io menjadi dapat diakses.

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

Image container besar

Jika image container Template Fleksibel Anda berukuran 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 penarikan.
  • Gunakan flag --launcher-machine-type untuk memilih jenis mesin dengan lebih banyak core CPU, yang membantu menarik image lebih cepat dan menghasilkan peluncuran yang lebih cepat.
  • Perpanjang waktu tunggu peluncuran melebihi batas default 12 menit (720 detik) menggunakan flag --launcher-vm-timeout-secs di gcloud CLI atau opsi peluncuran ft_launch_timeout_secs di REST API dan Managed Service untuk Apache Airflow. Untuk mengetahui contohnya, lihat Memperpanjang waktu tunggu peluncuran Template Flex.

Memeriksa apakah program peluncur gagal keluar

Program yang membuat pipeline harus selesai sebelum pipeline dapat diluncurkan. Error polling dapat mengindikasikan bahwa prosesnya terlalu lama.

Beberapa hal yang dapat Anda lakukan untuk menemukan penyebabnya 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 hingga thread ini digabungkan.
  • Dalam kode yang menentukan pipeline Anda, jangan gunakan waitUntilFinish (untuk Java) atau wait_until_finish (untuk Python). Fungsi ini memblokir program agar tidak keluar, sehingga mencegah Template Flex meluncurkan pipeline.

Pipeline yang diluncurkan secara langsung dan 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 mungkin dapat menyelesaikan masalah.

Kode yang berjalan lama di VM peluncur

Jika kode dalam program utama Anda memerlukan waktu terlalu lama untuk dieksekusi, Template Flex mungkin akan 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. Jika pipeline Anda masih memerlukan waktu lebih dari 12 menit untuk diluncurkan setelah Anda mengoptimalkan inisialisasi, lihat Memperpanjang waktu tunggu peluncuran Template Flex.

Error jaringan atau Cloud Storage yang terjadi sesekali

Error "Waktu tunggu habis dalam file hasil polling" atau "Gagal membaca file hasil" yang terputus-putus dapat terjadi karena latensi jaringan yang tinggi atau masalah sementara pada Cloud Storage API. Pertentangan jaringan kronis di VPC Anda, khususnya dalam jalur Akses Google Pribadi, sering kali menyebabkan latensi 400–500 md.

"Waktu tunggu habis dalam file hasil polling" biasanya merupakan kegagalan lambat, sedangkan "Gagal membaca file hasil" adalah kegagalan cepat, tetapi keduanya sering kali menunjukkan masalah konektivitas mendasar yang sama.

Untuk mendiagnosis kegagalan yang terputus-putus 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. Memantau metrik Cloud Storage API:

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

      Buka Enabled APIs & services

    2. Filter dan pilih Cloud Storage API.

    3. Tinjau diagram untuk Traffic (byte yang dikirim dan diterima) dan Rasio error.

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

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

Memverifikasi 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 Fleksibel 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, paketkan dependensi terlebih dahulu saat membuat template untuk menghindari keharusan mendownload atau menginstal dependensi selama peluncuran template. Untuk mengetahui informasi selengkapnya, lihat bagian Dependensi paket untuk Python di "Mengonfigurasi Template Flex". Jika penahapan dependensi atau pembuatan grafik eksekusi masih melebihi waktu tunggu peluncuran default selama 12 menit, lihat Memperpanjang waktu tunggu peluncuran Template Flex.

Memperpanjang waktu tunggu peluncuran Template Flex

Secara default, Dataflow menerapkan waktu tunggu 720 detik (12 menit) pada fase peluncuran Template Flex. Jika proses mengambil image container besar, menyiapkan dependensi, atau membuat grafik eksekusi yang kompleks memerlukan waktu lebih dari 720 detik, Anda dapat meningkatkan waktu tunggu ini dengan mengonfigurasi opsi waktu tunggu peluncuran untuk metode peluncuran Anda.

gcloud CLI

Untuk memperpanjang waktu tunggu VM peluncur saat Anda menjalankan Template Flex dari gcloud CLI, teruskan flag --launcher-vm-timeout-secs ke perintah gcloud dataflow flex-template run:

gcloud dataflow flex-template run JOB_NAME \
  --template-file-gcs-location=TEMPLATE_GCS_PATH \
  --region=REGION \
  --launcher-vm-timeout-secs=TIMEOUT_SECONDS

Ganti nilai berikut:

  • JOB_NAME: nama tugas Dataflow Anda.
  • TEMPLATE_GCS_PATH: Cloud Storage URI dari file spesifikasi Template Fleksibel Anda, seperti gs://my-bucket/templates/my-template.json.
  • REGION: region Dataflow tempat tugas dijalankan.
  • TIMEOUT_SECONDS: durasi waktu tunggu VM peluncur dalam detik. Tentukan bilangan bulat positif tanpa akhiran unit. Waktu tunggu defaultnya adalah 720, yaitu 12 menit. Untuk memperpanjang waktu tunggu, tentukan bilangan bulat yang lebih besar dari 720 dan hingga 5400, yaitu 90 menit, seperti 1200 untuk 20 menit atau 1800 untuk 30 menit.

REST API

Saat Anda meluncurkan Template Flex dengan memanggil endpoint REST projects.locations.flexTemplates.launch, tetapkan kunci ft_launch_timeout_secs di peta launchParameter.launchOptions ke string yang berisi durasi waktu tunggu dalam detik sebagai bilangan bulat, tanpa akhiran unit:

{
  "launchParameter": {
    "jobName": "JOB_NAME",
    "containerSpecGcsPath": "TEMPLATE_GCS_PATH",
    "launchOptions": {
      "ft_launch_timeout_secs": "TIMEOUT_SECONDS"
    }
  }
}

Ganti nilai berikut:

  • JOB_NAME: nama tugas Dataflow Anda.
  • TEMPLATE_GCS_PATH: Cloud Storage URI file spesifikasi Template Fleksibel Anda, seperti gs://my-bucket/templates/my-template.json.
  • TIMEOUT_SECONDS: durasi waktu tunggu VM peluncur dalam detik. Tentukan bilangan bulat positif sebagai string tanpa akhiran unit. Waktu tunggu default adalah "720", yaitu 12 menit. Untuk memperpanjang waktu tunggu, tentukan bilangan bulat yang lebih besar dari 720 dan hingga 5400, yaitu 90 menit, seperti "1200" untuk 20 menit atau "1800" untuk 30 menit.

Managed Airflow

Saat Anda mengorkestrasi tugas Template Fleksibel di Managed Airflow atau Apache Airflow dengan operator DataflowStartFlexTemplateOperator, sertakan kunci ft_launch_timeout_secs di bawah launchParameter.launchOptions dalam kamus body:

from airflow.providers.google.cloud.operators.dataflow import (
    DataflowStartFlexTemplateOperator,
)

start_flex_template = DataflowStartFlexTemplateOperator(
    task_id="start_flex_template",
    project_id="PROJECT_ID",
    location="REGION",
    body={
        "launchParameter": {
            "jobName": "JOB_NAME",
            "containerSpecGcsPath": "TEMPLATE_GCS_PATH",
            "launchOptions": {
                "ft_launch_timeout_secs": "TIMEOUT_SECONDS",
            },
        }
    },
)

Ganti nilai berikut:

  • PROJECT_ID: ID project Google Cloud Anda.
  • REGION: region Dataflow tempat tugas dijalankan.
  • JOB_NAME: nama tugas Dataflow Anda.
  • TEMPLATE_GCS_PATH: Cloud Storage URI file spesifikasi Template Fleksibel Anda, seperti gs://my-bucket/templates/my-template.json.
  • TIMEOUT_SECONDS: durasi waktu tunggu VM peluncur dalam detik. Tentukan bilangan bulat positif sebagai string tanpa akhiran unit. Waktu tunggu default adalah "720", yaitu 12 menit. Untuk memperpanjang waktu tunggu, tentukan bilangan bulat yang lebih besar dari 720 dan hingga 5400, yaitu 90 menit, seperti "1200" untuk 20 menit atau "1800" untuk 30 menit.

Kegagalan peluncuran tugas

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

Izin ditolak saat memuat file template

Saat Anda mencoba menjalankan template yang disediakan Google menggunakan gcloud CLI, Anda akan melihat error yang mirip dengan berikut ini:

ERROR: (gcloud.dataflow.flex-template.run) PERMISSION_DENIED: Template file
failed to load: TEMPLATE_PATH. Permissions denied.
USER does not have storage.objects.get access to the Google
Cloud Storage object. Operations on resource are denied due to an IAM
Principal Access Boundary Policy.

TEMPLATE_PATH adalah jalur ke template di bucket Cloud Storage yang berisi template yang disediakan Google, seperti gs://dataflow-templates atau gs://dataflow-templates-REGION_NAME.

Jika organisasi Anda menggunakan kebijakan principal access boundary (PAB), principal (seperti pengguna atau akun layanan) mungkin diblokir agar tidak dapat melihat dan menjalankan template yang disediakan Google. Untuk mengatasi masalah ini, coba panduan di Mengakses template yang disediakan Google dengan kebijakan batas akses utama.

Masalah saat aplikasi baru dibuka

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

Untuk mengaktifkan logging bagi 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...

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:

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 jika 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 diberikan, 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 kerja 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 Java Apache Beam dari internet. Paket ini diperlukan saat Anda menjalankan tugas multibahasa 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 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 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 Fleksibel, 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.

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 template dan image, sebelum membangun 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, biasanya e2-standard-2. Pilihan ini tidak bergantung pada worker machineType. Error kehabisan resource dapat terjadi jika jenis mesin default ini tidak tersedia di region atau zona tugas. Untuk menggunakan jenis mesin tertentu, tetapkan launcherMachineType.

Untuk mengatasi masalah ini, gunakan salah satu strategi berikut:

  • Perbarui jenis mesin peluncur ke jenis mesin yang berbeda dan coba lagi tugas tersebut.
  • Jika Anda menetapkan parameter zone, hapus parameter tersebut agar Dataflow dapat menempatkan VM peluncur di zona yang memiliki kapasitas.
  • Luncurkan Template Flex Anda dari region yang berbeda.

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, mungkin akan terjadi penundaan yang signifikan 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 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.

Untuk mengatasi masalah ini, gunakan metode yang sesuai untuk jenis template Anda.

Template Flex

Untuk Template Flex, gunakan flag --additional-pipeline-options untuk meneruskan opsi pipeline sebagai string. Misalnya, menggunakan perintah gcloud dataflow flex-template run:

gcloud dataflow flex-template run JOB_NAME \
--template-file-gcs-location=GCS_TEMPLATE_PATH \
--additional-pipeline-options=defaultSdkHarnessLogLevel=WARN,defaultWorkerLogLevel=WARN

Ganti nilai berikut:

  • JOB_NAME: nama tugas Dataflow Anda
  • GCS_TEMPLATE_PATH: jalur Cloud Storage ke file template
Template klasik

Untuk template klasik, solusinya adalah menyalin file spesifikasi template ke bucket Cloud Storage dan menambahkan 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 flag berikut saat Anda menjalankan template.

--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 level 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, konfigurasikan 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 Logback logger dengan implementasi appender JSON kustom. Untuk mengetahui informasi selengkapnya, lihat Contoh konfigurasi 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 worker Dataflow akan memiliki tingkat keparahan yang sesuai.

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