Memecahkan Masalah Template Flex

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

Memecahkan masalah waktu tunggu polling

Bagian ini menjelaskan langkah-langkah untuk mengidentifikasi penyebab waktu tunggu polling.

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 telah 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 membutuhkan waktu penyelesaian yang terlalu lama.
  5. Opsi pipeline sedang ditimpa.
  6. (Khusus Python) Ada masalah dengan file requirements.txt.
  7. Terjadi error sementara.

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

Memverifikasi entrypoint Docker

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

Periksa entrypoint 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 akan diganti. Pulihkan $TEMPLATE_IMAGE ke default.

Memeriksa izin akun layanan

Pastikan akun layanan yang disebutkan dalam pesan memiliki izin berikut:

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

Memeriksa apakah program peluncur gagal keluar

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

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

  • Periksa log tugas dan lihat apakah operasi apa pun yang tampaknya membutuhkan waktu lama untuk diselesaikan. Contohnya adalah permintaan untuk resource eksternal.
  • Pastikan tidak ada thread yang memblokir program agar tidak keluar. Beberapa klien mungkin membuat threadnya sendiri, dan jika klien tersebut tidak dinonaktifkan, program akan menunggu selamanya hingga thread tersebut digabungkan.

Pipeline yang diluncurkan langsung tanpa menggunakan template tidak memiliki batasan ini. Oleh karena itu, jika pipeline berfungsi secara langsung tetapi tidak sebagai template, penggunaan template mungkin merupakan akar masalahnya. Menemukan masalah dalam template dan memperbaiki template dapat menyelesaikan masalah tersebut.

Memverifikasi apakah opsi pipeline yang diperlukan disembunyikan

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

Menghapus 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, 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 akan berada dalam antrean selama beberapa periode, gagal dijalankan, lalu menampilkan error berikut:

Timeout in polling

File requirements.txt yang digunakan untuk menginstal dependensi yang diperlukan akan 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 download dan kompilasi setiap dependensi langsung dan tidak langsung dalam file requirements.txt. Beberapa dependensi mungkin memerlukan waktu beberapa menit untuk dikompilasi. Secara khusus, PyArrow mungkin memerlukan waktu untuk melakukan kompilasi. 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 mengemas dependensi. 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 tersebut.

Masalah startup awal

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

Guna mengaktifkan logging untuk template Java, tetapkan opsi enableLauncherVmSerialPortLogging ke true. Guna mengaktifkan logging untuk template Python dan Go, tetapkan opsi enable_launcher_vm_serial_port_logging ke true. Di Konsol Google Cloud, parameter tersebut dicantumkan dalam Parameter opsional sebagai Enable Launcher VM Serial Port Logging.

Anda dapat melihat log output port serial dari 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 Fleksibel, tugas Anda mungkin gagal dengan salah satu 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

Atau:

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 opsi inisialisasi pipeline yang diperlukan ditimpa. Saat menggunakan Template Fleksibel, Anda dapat mengonfigurasi beberapa tetapi tidak semua opsi pipeline selama inisialisasi pipeline. Jika argumen command line yang diperlukan oleh Flex Template ditimpa, tugas mungkin mengabaikan, mengganti, atau menghapus 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:

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

Izin ditolak pada resource

Saat Anda mencoba menjalankan tugas dari Template Fleksibel, 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 Flex.

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

Tanda diberikan, tetapi tidak ditentukan

Saat Anda mencoba menjalankan Template Go Flex 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 pada 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.

Penundaan peluncur Template Flex

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

Untuk mengatasi masalah ini, luncurkan Template Flex dari wilayah yang berbeda.

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

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

Setelah 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

Saat peluncuran Template Fleksibel 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.

Akar penyebab kegagalan peluncuran biasanya muncul di log sebelum pesan ini dengan tingkat keparahan INFO. Meskipun level log ini mungkin salah, hal ini wajar karena peluncur template Flex tidak memiliki cara untuk mengekstrak detail tingkat keparahan dari pesan log yang dihasilkan oleh aplikasi Apache Beam.

Jika ingin melihat tingkat keparahan yang benar untuk setiap pesan di log peluncur, konfigurasikan template 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 Logback logger dengan implementasi appender JSON kustom. Untuk mengetahui informasi selengkapnya, lihat Konfigurasi contoh Logback dan kode contoh penunjang JSON di GitHub.

Masalah ini hanya memengaruhi log yang dibuat oleh peluncur Template Fleksibel saat pipeline diluncurkan. Saat peluncuran berhasil dan pipeline berjalan, log yang dihasilkan oleh pekerja Dataflow 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.