Memecahkan masalah transfer sistem file

Dokumen ini menjelaskan cara memecahkan masalah dan menyelesaikan masalah transfer dan agen, serta tempat menemukan log agen untuk membantu Anda memecahkan masalah.

Error

Tabel berikut menjelaskan pesan error transfer, dan cara mengatasinya:

Pesan error Jenis error Arti error Cara mengatasi error
Diubah selama transfer FILE_MODIFIED_FAILURE File sumber diubah selama transfer setiap kali Storage Transfer Service mencoba menyalin file sumber. Cegah penulisan ke file yang ditentukan selama operasi Storage Transfer Service berikutnya.
Gagal mentransfer PRECONDITION_FAILURE Objek Cloud Storage yang terkait dengan file sumber diubah setiap kali Storage Transfer Service mencoba mengupload file. Cegah beberapa tugas transfer menulis file yang sama ke bucket Cloud Storage yang sama dengan menggunakan awalan objek Cloud Storage yang unik saat Anda membuat tugas transfer.
Direktori sumber tidak ditemukan SOURCE_DIR_NOT_FOUND Jalur sumber yang ditentukan salah, atau jalurnya benar, tetapi tidak semua agen memiliki akses ke jalur tersebut. Periksa konfigurasi tugas transfer dan pastikan bahwa:
Tidak dapat menemukan direktori sumber atau tujuan tugas ROOT_DIR_NOT_FOUND Jalur sumber/tujuan yang ditentukan salah, atau jalurnya benar, tetapi tidak semua agen memiliki akses ke jalur tersebut. Periksa konfigurasi tugas transfer dan pastikan bahwa:
File tidak ditemukan FILE_NOT_FOUND_FAILURE File sumber ditemukan, tetapi dihapus sebelum ditransfer ke Cloud Storage. Jika file tidak sengaja dihapus, pulihkan file tersebut agar tugas transfer berikutnya dapat menguploadnya.
Gagal menemukan bucket tujuan BUCKET_NOT_FOUND Bucket tujuan tidak ada di Cloud Storage. Pastikan ejaan bucket tujuan sudah benar dan bucket tersebut ada.
Gagal menemukan objek metadata internal METADATA_OBJECT_
NOT_FOUND_FAILURE
Storage Transfer Service menyimpan metadata di bucket tujuan dengan awalan storage-transfer. Jika file metadata dihapus sebelum operasi transfer yang sesuai selesai, error ini akan ditampilkan. Hindari menghapus objek dengan awalan storage-transfer/ di bucket tujuan hingga semua tugas transfer selesai.
Gagal karena nama file tidak valid INVALID_FILE_NAME Jalur file sumber tidak valid. Verifikasi dan perbaiki jalur file yang ditentukan. Pastikan jalur menggunakan karakter yang didukung oleh Cloud Storage.
Gagal karena kelas penyimpanan tidak valid INVALID_FILE_STORAGE_CLASS Kelas penyimpanan untuk sumber yang diberikan tidak mengizinkan pembacaan. Temukan dokumentasi untuk penyedia cloud Anda guna menentukan cara memasukkan data ke dalam kelas penyimpanan yang memungkinkan penyalinan data.
Gagal karena URI sesi upload yang dapat dilanjutkan tidak valid SESSION_URI_INVALID ID upload yang dapat dilanjutkan atau URI sesi sudah tidak berlaku atau dibatalkan. Kegagalan dicoba lagi secara tidak benar. Hubungi dukungan.
Gagal karena ukuran file tidak valid INVALID_FILE_SIZE Ukuran file tidak valid. Pastikan ukuran file >= 0 dan <= 5 TiB (ukuran objek Cloud Storage maksimum) untuk transfer ke Cloud Storage.
Gagal karena izin PERMISSION_FAILURE dan UNAUTHENTICATED Agen transfer tidak memiliki izin yang memadai untuk melakukan operasi. Ada dua kemungkinan penyebab error ini:
  • Agen tidak memiliki izin Google Cloud yang memadai.
  • Agen tidak dapat membaca file atau direktori karena izin yang tidak memadai pada sistem file sumber.

Pastikan hal berikut:

  • Pastikan agen Anda memiliki peran IAM berikut:
    • roles/storagetransfer.transferAgent
    • roles/storage.objectUser untuk semua bucket tujuan atau perantara

    Salah satu peran ini dapat diberikan ke akun layanan yang digunakan oleh agen, atau pengguna dengan peran ini dapat menggunakan kredensial default mereka saat menginstal agen.

  • Pastikan semua jalur pada sistem file sumber dapat dibaca oleh setiap agen.
Object is subject to bucket's retention policy and cannot be deleted, overwritten or archived PERMISSION_FAILURE Bucket memiliki kebijakan retensi yang berlaku dan objek sudah ada di bucket. Storage Transfer Service tidak dapat menimpa objek yang ada di bucket. Error ini dapat ditampilkan jika file berubah di sumber, atau jika Storage Transfer Service mencoba mengupload dua kali karena kondisi jaringan dan upload pertama berhasil. Pastikan data di bucket Cloud Storage Anda sesuai dengan harapan Anda. Anda dapat mengonfirmasi bahwa ukuran dan waktu modifikasi (mtime) file sumber cocok dengan objek Cloud Storage yang sesuai dengan menjalankan ulang tugas dan mengonfirmasi bahwa tidak ada error.
Layanan tidak memiliki izin yang memadai SERVICE_PERMISSION_FAILURE Storage Transfer Service tidak memiliki izin yang memadai untuk melakukan operasi. Storage Transfer Service menggunakan agen layanan, biasanya dalam format project-PROJECT_NUMBER@storage-transfer-service., untuk mengakses resource. Untuk menentukan PROJECT_NUMBER spesifik Anda, gunakan panggilan API googleserviceaccounts.get. Pastikan akun layanan memiliki peran berikut:
  • roles/storagetransfer.serviceAgent untuk project.
  • roles/storage.objectCreator, roles/storage.objectViewer, dan roles/storage.legacyBucketReader untuk semua bucket tujuan atau perantara (lihat Mengonfigurasi akses ke sink: Cloud Storage).
Agen tidak didukung AGENT_UNSUPPORTED_VERSION Versi agen tidak lagi kompatibel dengan Storage Transfer Service. Error ini bersifat sementara, terkait dengan update agen yang buruk. Jika terjadi, lakukan hal berikut:
  1. Hentikan semua agen Anda.
  2. Tarik image docker terbaru dengan menjalankan: sudo docker pull gcr.io/cloud-ingest/tsop-agent:latest
  3. Berikan perintah run Docker untuk memulai semua container agen Anda.
Jika masalah berlanjut, hubungi tim dukungan Anda.
Gagal karena ketidakcocokan hash HASH_MISMATCH_FAILURE Setiap kali Storage Transfer Service mencoba mengupload file ini, byte yang diupload rusak. Hal ini menyebabkan hash file lokal tidak cocok dengan hash objek Cloud Storage yang dihasilkan. Error ini mungkin disebabkan oleh sejumlah potensi masalah. Jika Anda melihat persentase kecil kegagalan ketidakcocokan hash (kurang dari 1%) dalam transfer besar, coba lagi file yang gagal. Jika Anda melihat persentase kegagalan ketidakcocokan hash yang besar (1% atau lebih), sebaiknya selidiki potensi kegagalan memori, CPU, atau hardware lainnya di mesin agen.
Gagal karena mode file yang tidak didukung UNSUPPORTED_FILE_MODE Storage Transfer Service menemukan file dengan mode yang tidak didukung, seperti perangkat, soket, pipa bernama, atau file tidak beraturan. Hapus jenis file khusus ini dari direktori sumber.
Gagal karena terjadi error pada sistem file FILESYSTEM_ERROR Agen mengalami error sistem file atau sistem operasi saat melakukan operasi sistem file seperti read, seek, atau stat. Baca deskripsi kegagalan untuk memahami operasi sistem file yang gagal. Pastikan sistem file dapat diakses oleh agen lokal dan responsif terhadap operasi file dasar.
Gagal karena tidak ada ruang tersisa di sistem file FILESYSTEM_NO_SPACE_ON_DEVICE Agen kehabisan ruang saat melakukan operasi sistem file seperti membuka atau menulis. Baca deskripsi kegagalan untuk memahami operasi sistem file yang gagal. Pastikan sistem file memiliki ruang yang cukup untuk melakukan operasi file.
Gagal karena error yang tidak diketahui UNKNOWN_FAILURE Terjadi error tidak terduga. Baca deskripsi kegagalan. Jika deskripsi kegagalan tidak berisi informasi yang cukup untuk menyelesaikan masalah, hubungi dukungan.
Gagal karena spesifikasi tidak valid INVALID_SPEC Agen menerima spesifikasi internal yang rusak. Periksa kerusakan data pada host agen dan hubungi dukungan jika Anda tidak dapat menemukannya.
Gagal karena file manifes kosong atau tidak valid CONFORMANCE_FAILURE Agen tidak dapat membaca atau mendapatkan byte CSV yang valid karena format atau entri CSV yang tidak valid. Pastikan entri manifes adalah jalur file yang valid. Jika deskripsi kegagalan tidak berisi informasi yang cukup untuk menyelesaikan masalah, hubungi dukungan.
Kembali ke upload yang dapat dilanjutkan, bukan upload multibagian, karena error izin ditolak PERMISSION_FAILURE Upload multibagian telah diaktifkan untuk transfer ini, tetapi izin yang benar belum ditetapkan di bucket. Lihat Mengonfigurasi akses ke sink: Cloud Storage untuk mengetahui izin yang diperlukan.
Entri dicantumkan tidak berurutan INCOMPATIBLE_LIST_ORDER_FAILURE Sistem file sumber menampilkan daftar file dalam urutan yang tidak kompatibel dengan Storage Transfer Service. Storage Transfer Service mengharuskan sistem file sumber menampilkan file dalam urutan yang diurutkan secara leksikografis. Pastikan sistem file menampilkan file dalam urutan yang diurutkan secara leksikografis.

Melihat log agen

Log agen berisi informasi yang relevan dengan proses agen, dan dapat membantu Anda memecahkan masalah koneksi agen. Jika agen Anda tercantum sebagai terhubung di konsol Google Cloud dan Anda mengalami kegagalan transfer, lihat Melihat detail error untuk melihat contoh error transfer. Untuk melihat log yang berisi data setiap file yang dipertimbangkan Storage Transfer Service selama transfer, lihat Melihat log transfer.

Secara default, log agen disimpan di /tmp. Anda dapat mengubah lokasi dengan opsi command line --log-dir=logs-directory.

Log diberi nama:

agent.hostname.username.log.log-level.timestamp

Komponen nama log adalah sebagai berikut:

  • hostname - nama host tempat agen berjalan.
  • username - nama pengguna yang menjalankan agen.
  • log-level adalah salah satu dari:
    • INFO - pesan informasi
    • ERROR - error yang terjadi selama transfer, tetapi tidak mencegah tugas transfer berlanjut.
    • FATAL - error yang terjadi yang mencegah tugas transfer berlanjut.
  • timestamp - stempel waktu dalam format YYYYMMDD-hhmmss.thread-id.

Direktori log berisi symlink ke log terbaru untuk setiap tingkat prioritas:

  • agent.ERROR
  • agent.FATAL
  • agent.INFO

Kecepatan transfer lambat

Jika data Anda memerlukan waktu lama untuk ditransfer, periksa hal berikut:

  1. Throughput baca sistem file Anda harus sekitar 1,5 kali kecepatan upload yang Anda inginkan. Anda dapat menggunakan FIO untuk menguji throughput baca sistem file Anda.

    Instal fio:

     sudo apt install -y fio
     

    Buat direktori baru fiotest:

     TEST_DIR=/mnt/mnt_dir/fiotest
     sudo mkdir -p $TEST_DIR
     

    Menguji throughput baca:

     sudo fio --directory=$TEST_DIR --direct=1
        --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8
        --time_based=1 --runtime=180 --name=read_test --size=1G
     

    Setelah Anda menjalankan perintah di atas, Fio akan membuat laporan. Baris berlabel "bw" mewakili total bandwidth gabungan dari semua thread, dan dapat digunakan sebagai proxy untuk throughput baca.

  2. Gunakan iPerf3 untuk memeriksa bandwidth internet yang tersedia ke Storage Transfer Service.

  3. Pastikan setiap agen transfer Anda memiliki minimal 4 vCPU dan RAM 8 GB.

Jika Anda telah memeriksa kondisi di atas dan masih mengalami waktu transfer yang lama, Anda dapat menambahkan agen tambahan untuk meningkatkan jumlah koneksi serentak ke sistem file data Anda.

Untuk mengetahui informasi selengkapnya tentang cara memaksimalkan performa agen transfer, lihat Praktik terbaik agen.

Memecahkan masalah error agen

Bagian berikut menjelaskan cara memecahkan masalah dan menyelesaikan error agen transfer:

Agen tidak terhubung

Jika agen transfer tidak ditampilkan sebagai terhubung dalam konsol Google Cloud :

  1. Pastikan agen dapat terhubung ke Cloud Storage API:

    1. Jalankan perintah berikut dari mesin yang sama dengan agen transfer untuk menguji koneksi agen ke Cloud Storage API:

      gcloud storage cp test.txt gs://my-bucket

      Ganti:

      my-bucket dengan nama bucket Cloud Storage Anda.

  2. Jika project Anda menggunakan Kontrol Layanan VPC, lihat log agen untuk menemukan error. Jika Kontrol Layanan VPC salah dikonfigurasi, log agen INFO akan berisi error berikut:

    Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

    Dalam output ini:

Agen terhubung, tetapi tugas gagal

Jika agen ditampilkan sebagai terhubung, tetapi tugas transfer gagal, periksa detail error tugas yang gagal.

Proxy menolak alamat IP

Jika Anda menjalankan di balik proxy seperti Squid dan menggunakan daftar yang diizinkan, Anda mungkin melihat permintaan ditolak karena alamat IP yang digunakan, bukan nama host.

Untuk mengatasi masalah ini, gunakan perintah docker run untuk menjalankan agen dan tambahkan flag berikut:

--transfer-service-endpoint=storagetransfer.:443

Jika Anda menggunakan endpoint alternatif untuk menjangkau (misalnya, untuk Private Service Connect), ganti dengan endpoint alternatif.

Agen tidak dapat terhubung ke endpoint HTTPS menggunakan sertifikat yang ditandatangani sendiri

Jika agen Anda tidak dapat terhubung ke endpoint HTTPS menggunakan sertifikat yang ditandatangani sendiri, gunakan opsi -v tambahan untuk memasang paket sertifikat kustom Anda ke lokasi default container (/etc/ssl/certs).

Untuk melakukannya, ubah perintah docker run dengan menambahkan flag berikut:

-v PATH_TO_LOCAL_CERT:/etc/ssl/certs/ca-certificates.crt

Ganti:

  • PATH_TO_LOCAL_CERT dengan jalur ke file sertifikat kustom Anda.

Agen gagal memulai: KDC tidak merespons negosiasi FAST dengan tepat

Jika saat mencoba memulai agen transfer untuk transfer HDFS, agen gagal memulai dan menampilkan error yang mirip dengan berikut ini:

Failed to start the agent, err = failed to create HDFS client: Couldn't find the hdfs client: no available namenodes: SASL handshake: [Root cause: KRBMessage_Handling_Error] KRBMessage_Handling_Error: AS Exchange Error: AS_REP is not valid or client password/keytab incorrect < KRBMessage_Handling_Error: KDC did not respond appropriately to FAST negotiation

Error ini terjadi jika Kerberos Key Distribution Center (KDC) Anda tidak mendukung negosiasi FAST, yang dicoba digunakan oleh agen secara default untuk transfer HDFS.

Untuk mengatasi masalah ini, cegah agen menggunakan negosiasi FAST dengan menambahkan flag --kerberos-disable-pa-fx-fast saat Anda memulai agen.

Flag ini hanya didukung saat menjalankan agen menggunakan docker atau podman. Fitur ini tidak didukung saat menggunakan perintah gcloud transfer agents install.

Tambahkan flag ke perintah docker run atau podman run Anda sebagai berikut:

docker run --rm -v /usr/local/transfer_agent:/tmp/transfer_agent \
  gcr.io/cloud-ingest/tsop-agent:latest \
  --project-id=PROJECT_ID \
  --hostname=$(hostname) \
  --kerberos-disable-pa-fx-fast

Lihat Menginstal dan menjalankan agen transfer untuk mengetahui detail selengkapnya tentang perintah docker dan podman.