Memecahkan masalah transfer sistem file

Dokumen ini menjelaskan cara memecahkan 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.	Mencegah 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 tersebut.	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 jalur sudah benar, tetapi tidak semua agen memiliki akses ke jalur tersebut.	Periksa konfigurasi tugas transfer dan pastikan: Jalur sumber yang tercantum sudah benar Setiap agen memiliki akses ke direktori
Tidak dapat menemukan direktori sumber atau tujuan tugas	ROOT_DIR_NOT_FOUND	Jalur sumber/tujuan yang ditentukan salah, atau jalur sudah benar, tetapi tidak semua agen memiliki akses ke jalur tersebut.	Periksa konfigurasi tugas transfer dan pastikan: Jalur sumber/tujuan yang tercantum sudah benar Agen yang relevan memiliki akses ke direktori
File tidak ditemukan	FILE_NOT_FOUND_FAILURE	File sumber ditemukan, tetapi dihapus sebelum ditransfer ke Cloud Storage.	Jika tidak sengaja menghapus file, pulihkan agar tugas transfer berikutnya dapat menguploadnya.
Gagal menemukan bucket tujuan	BUCKET_NOT_FOUND	Bucket tujuan tidak ada di Cloud Storage.	Verifikasi bahwa ejaan bucket tujuan sudah benar dan bahwa ejaan 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 sampai 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 tersebut menggunakan karakter yang didukung oleh Cloud Storage.
Gagal karena URI sesi upload yang dapat dilanjutkan tidak valid	SESSION_URI_INVALID	ID upload atau URI sesi yang dapat dilanjutkan sudah tidak berlaku atau dibatalkan.	Kegagalan dicoba lagi dengan 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 maks) untuk transfer ke Cloud Storage.
Gagal karena izin	PERMISSION_PROGRESS dan UNAUTHENTICATED	Agen transfer tidak memiliki izin yang memadai untuk menjalankan operasi. Ada dua kemungkinan untuk error ini: Seorang agen tidak memiliki izin Google Cloud yang memadai. Agen tidak dapat membaca file atau direktori karena izin pada sistem file sumber tidak memadai.	Pastikan hal berikut: Pastikan agen Anda memiliki peran IAM berikut: `storagetransfer.transferAgent` `storage.admin` untuk semua bucket tujuan Kedua 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 di sistem file sumber dapat dibaca oleh setiap agen.
Objek tunduk pada kebijakan retensi bucket dan tidak dapat dihapus, ditimpa, atau diarsipkan	PERMISSION_FAILURE	Bucket memiliki kebijakan retensi yang berlaku dan objek sudah ada di dalam bucket. Storage Transfer Service tidak dapat menimpa objek yang sudah ada di bucket. Error ini dapat ditampilkan jika file diubah di sumbernya, atau jika Storage Transfer Service mencoba mengupload dua kali karena kondisi jaringan dan upload pertama berhasil.	Verifikasi bahwa data dalam bucket Cloud Storage sesuai dengan ekspektasi Anda. Anda dapat mengonfirmasi bahwa ukuran dan waktu perubahan (mtime) file sumber cocok dengan objek Cloud Storage dengan menjalankan kembali tugas tersebut dan mengonfirmasi bahwa tidak ada error.
Layanan tidak memiliki izin yang memadai	SERVICE_PERMISSION_FAILURE	Storage Transfer Service tidak memiliki izin yang memadai untuk menjalankan operasi.	Storage Transfer Service menggunakan akun layanan yang dikelola Google, biasanya dalam format `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com`, untuk mengakses resource. Untuk menentukan `PROJECT_NUMBER` spesifik, gunakan panggilan API `googleserviceaccounts.get`. Pastikan akun layanan memiliki peran berikut: `roles/storagetransfer.serviceAgent` untuk project. `roles/storage.admin` untuk semua bucket tujuan.
Agen tidak didukung	AGENT_UNSUPPORTED_VERSION	Versi agen tidak lagi kompatibel dengan Storage Transfer Service.	Ini adalah error sementara, terkait dengan update agen yang buruk. Jika masalah terjadi, lakukan tindakan berikut: Hentikan semua agen Anda. Dapatkan image docker terbaru dengan menjalankan: `sudo docker pull gcr.io/cloud-ingest/tsop-agent` Berikan perintah Docker `run` untuk memulai semua container agen Anda. Jika masalah masih 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 mengakibatkan hash file lokal tidak cocok dengan hash objek Cloud Storage yang dihasilkan.	Error ini dapat disebabkan oleh sejumlah potensi masalah. Jika Anda melihat sebagian kecil kegagalan ketidakcocokan hash (kurang dari 1%) dalam transfer besar, coba lagi file yang gagal. Jika Anda melihat sejumlah besar kegagalan ketidakcocokan hash (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 teratur.	Hapus jenis file khusus ini dari direktori sumber.
Gagal karena terjadi error dalam sistem file	FILESYSTEM_ERROR	Seorang agen mengalami error sistem file atau sistem operasi saat menjalankan operasi sistem file seperti baca, cari, atau stat.	Baca deskripsi kegagalan untuk memahami operasi sistem file mana yang gagal. Pastikan sistem file dapat diakses oleh agen lokal dan responsif terhadap operasi file dasar.
Gagal karena error yang tidak diketahui	UNKNOWN_FAILURE	Terjadi error tidak terduga.	Baca deskripsi kegagalan. Jika deskripsi kegagalan tidak berisi informasi yang memadai untuk menyelesaikan masalah, harap 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 berupa jalur file yang valid. Jika deskripsi kegagalan tidak berisi informasi yang memadai untuk menyelesaikan masalah, harap 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 bagian Upload multibagian di Izin sistem file untuk izin yang diperlukan.

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 bagian Melihat error untuk melihat contoh error transfer. Untuk melihat log yang berisi data setiap file Storage Transfer Service yang dipertimbangkan 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 tersebut diberi nama:

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

Dengan keterangan:

hostname - nama host tempat agen berjalan.
username - nama pengguna yang menjalankan agen.
log-level adalah salah satu dari:
- INFO - pesan informasi
- ERROR - error terjadi selama transfer, tetapi tidak mencegah tugas transfer dilanjutkan.
- FATAL - terjadi error yang mencegah tugas transfer dilanjutkan.
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:

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

Instal fio:
```
 sudo apt install -y fio
 
```
Buat direktori baru fiotest:
```
 TEST_DIR=/mnt/mnt_dir/fiotest
 sudo mkdir -p $TEST_DIR
 
```
Uji 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 agregat dari semua thread, dan dapat digunakan sebagai proxy untuk throughput baca.
Gunakan iPerf3 untuk memeriksa bandwidth internet yang tersedia ke Storage Transfer Service.
Pastikan setiap agen transfer Anda memiliki minimal 4 vCPU dan RAM 8 GB.

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

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

Memecahkan masalah error agen

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

Agen tidak terhubung

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

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:
  
  gsutil cp test.txt gs://my-bucket
  
  Ganti:
  
  my-bucket dengan nama bucket Cloud Storage Anda.
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:
- id adalah ID unik untuk error Kontrol Layanan VPC

Agen terhubung, tetapi tugas gagal

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