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 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 selesai.
  5. Opsi pipeline ditimpa.
  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 pemecahan masalah berikut.

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 penampung 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 penampung Docker Anda akan diganti. Memulihkan $TEMPLATE_IMAGE ke setelan 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.
  • Image 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 polling memerlukan waktu terlalu lama.

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

  • Periksa log tugas dan lihat apakah ada operasi yang tampaknya memerlukan waktu lama untuk selesai. Contohnya adalah permintaan untuk resource eksternal.
  • 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 bergabung.

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

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.

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, yang sering kali mengakibatkan waktu tunggu habis.

Waktu tunggu polling saat menggunakan Python

Jika Anda menjalankan tugas Dataflow menggunakan Template Flex dan Python, tugas Anda mungkin dimasukkan ke dalam antrean selama jangka waktu tertentu, 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-staging 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 dikompilasi. PyArrow adalah dependensi tidak langsung yang digunakan oleh Apache Beam dan sebagian besar Library Klien Cloud.

Untuk mengoptimalkan performa tugas, gunakan Dockerfile atau penampung kustom untuk membuat paket 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 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 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 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 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, tetapi tidak semua opsi pipeline selama inisialisasi pipeline. Jika argumen command line yang diperlukan oleh Template Flex 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

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 Flex. Untuk daftar izin yang diperlukan, lihat Izin untuk menjalankan Template Flex.

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 guna menjalankan Template Flex.

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 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 yang diketahui 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 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:

  • 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. Masukkan 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 menginstal Java di lingkungan penampung Anda.

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 antrean pesan, penundaan yang signifikan dapat terjadi antara waktu Anda mengirimkan tugas dan waktu tugas diluncurkan.

Untuk mengatasi masalah ini, luncurkan Template Fleksibel Anda dari region 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.

"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

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 dalam log sebelum pesan ini dengan tingkat keparahan INFO. Meskipun level log ini mungkin salah, hal ini diharapkan, karena peluncur template Flex tidak memiliki cara untuk mengekstrak detail keparahan dari pesan log yang dihasilkan oleh aplikasi Apache Beam.

Jika Anda ingin melihat tingkat keparahan yang benar untuk setiap pesan dalam log peluncur, konfigurasikan template 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 kode contoh JSON appender 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 sesuai.

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