ファイルシステム転送のトラブルシューティング

このドキュメントでは、転送とエージェントに関する問題のトラブルシューティングと解決方法について説明します。また、問題のトラブルシューティングに役立つエージェントログを探す方法も説明します。

エラー

次の表に、転送エラーメッセージとその解決方法を示します。

エラーメッセージ	エラーの種類	エラーの意味	エラーの解決方法
Modified during transfer	FILE_MODIFIED_FAILURE	Storage Transfer Service がソースファイルのコピーを試みると、転送中にソースファイルが変更されます。	次の Storage Transfer Service オペレーションが実行されている間は、指定したファイルに書き込まないようにします。
Failed to transfer	PRECONDITION_FAILURE	Storage Transfer Service がファイルをアップロードするたびに、ソースファイルに関連付けられた Cloud Storage オブジェクトが変更されます。	転送ジョブを作成するときに一意の Cloud Storage オブジェクト接頭辞を使用し、複数の転送ジョブで同じファイルを同じ Cloud Storage バケットに書き込まないようにします。
Source directory not found	SOURCE_DIR_NOT_FOUND	指定されたソースパスが正しくありません。また、正しいパスを指定していても、一部のエージェントがパスにアクセスできない場合があります。	転送ジョブの構成で次のことを確認します。設定されているソースパスが正しいこと各エージェントがディレクトリに対するアクセス権を持っていること
Could not find the job's source or destination directory	ROOT_DIR_NOT_FOUND	指定されたソースパスまたは宛先パスが正しくありません。また、正しいパスを指定していても、一部のエージェントがパスにアクセスできない場合があります。	転送ジョブの構成で次のことを確認します。設定されているソースパスまたは宛先パスが正しいこと関連するエージェントがディレクトリへのアクセス権を持っていること
File not found	FILE_NOT_FOUND_FAILURE	ソースファイルが見つかりましたが、Cloud Storage に転送される前に削除されました。	ファイルが誤って削除された場合は、ファイルを復元し、次の転送ジョブでアップロードできるようにします。
Failed to find the destination bucket	BUCKET_NOT_FOUND	転送先バケットが Cloud Storage に存在しません。	転送先バケットのスペルが正しいことと、転送先バケットが存在することを確認します。
Failed to find an internal metadata object	METADATA_OBJECT_ NOT_FOUND_FAILURE	Storage Transfer Service は、接頭辞 `storage-transfer` を付けてメタデータを転送先バケットに保存します。対応する転送オペレーションが完了する前にメタデータファイルが削除されると、このエラーが表示されます。	すべての転送ジョブが完了するまで、転送先バケット内にある接頭辞が `storage-transfer/` のオブジェクトは削除しないでください。
Failed due to invalid file name	INVALID_FILE_NAME	ソースファイルのパスが無効です。	指定したファイルパスを確認して修正します。パスに Cloud Storage でサポートされている文字が使用されていることを確認します。
Failed due to invalid resumable upload session URI	SESSION_URI_INVALID	再開可能なアップロードの ID またはセッション URI が期限切れか、キャンセルされました。	失敗した処理が不適切に再試行されています。サポートにお問い合わせください。
Failed due to invalid file size	INVALID_FILE_SIZE	ファイルサイズが無効です。	Cloud Storage に転送するファイルのサイズが 0 以上 5 TiB（最大 Cloud Storage オブジェクトサイズ）以下であることを確認します。
Failed due to permissions	PERMISSION_FAILURE と UNAUTHENTICATED	オペレーションの実行に必要な権限が転送エージェントにありませんでした。このエラーには 2 つの可能性があります。エージェントに十分な Google Cloud 権限がない。ソースファイルシステムの権限が不十分なため、エージェントがファイルまたはディレクトリを読み取れない。	以下を確認してください。エージェントに次の Cloud IAM ロールがあることを確認します。 `storagetransfer.transferAgent` すべての転送先バケットに対する `storage.admin` どちらのロールも、エージェントが使用するサービスアカウントに付与できます。または、これらのロールを持つユーザーが、エージェントをインストールするときにデフォルトの認証情報を使用することもできます。ソースファイルシステム上のすべてのパスが各エージェントで読み取り可能であることを確認します。
Object is subject to bucket's retention policy and cannot be deleted, overwritten or archived	PERMISSION_FAILURE	バケットに保持ポリシーがあり、オブジェクトがすでにバケットに存在します。Storage Transfer Service は、バケット内の既存のオブジェクトを上書きできません。このエラーは、ソースでファイルが変更された場合、またはネットワークの状態が原因で Storage Transfer Service がアップロードを 2 回試行し、最初のアップロードが成功した場合に表示されます。	Cloud Storage バケット内のデータが、想定どおりの内容であることを確認します。ジョブを再実行してエラーがないことを確認することで、ソースファイルのサイズと修正時間（mtime）が Cloud Storage オブジェクトの対応するものと一致することを確認できます。
Service lacked sufficient permissions	SERVICE_PERMISSION_FAILURE	オペレーションの実行に必要な権限が Storage Transfer Service にありません。	Storage Transfer Service は、Google が管理するサービスアカウント（通常、`project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com` の形式）を使用してリソースにアクセスします。特定の `PROJECT_NUMBER` を確認するには、`googleserviceaccounts.get` API 呼び出しを使用します。サービスアカウントに次のロールがあることを確認します。プロジェクトに対する `roles/storagetransfer.serviceAgent` すべての転送先バケットに対する `roles/storage.admin`
Agent unsupported	AGENT_UNSUPPORTED_VERSION	エージェントのバージョンが Storage Transfer Service と互換性がありません。	これは一時的なエラーです。エージェントの更新の不備が原因で発生しています。この場合は、次のように対応します。すべてのエージェントを停止します。 `sudo docker pull gcr.io/cloud-ingest/tsop-agent` を実行して、最新の Docker イメージを pull します。 Docker `run` コマンドを発行して、すべてのエージェントコンテナを起動します。問題が解決しない場合は、サポートチームにお問い合わせください。
Failed due to hash mismatch	HASH_MISMATCH_FAILURE	Storage Transfer Service がこのファイルのアップロードを試みたときに、アップロードされたバイト数が破損しました。これにより、オンプレミスファイルのハッシュが Cloud Storage オブジェクトのハッシュと一致しません。	このエラーは、さまざまな問題が原因で発生する可能性があります。大量の転送でハッシュ不一致エラーの割合が低い場合（1% 未満）は、失敗したファイルを再試行します。ハッシュ不一致エラーの割合が高い場合（1% 以上）は、エージェントマシンのメモリ、CPU、その他のハードウェア障害の可能性について調査することをおすすめします。
Failed due to an unsupported file mode	UNSUPPORTED_FILE_MODE	Storage Transfer Service が、サポートされていないモードのファイル（デバイス、ソケット、名前付きパイプ、異常なファイルなど）を検出しました。	これらの特殊なファイル形式をソースディレクトリから削除します。
Failed due to an error in the file system	FILESYSTEM_ERROR	読み取り、シーク、統計などのファイルシステムオペレーションを実行したときに、エージェントがファイルシステムまたはオペレーティングシステムのエラーを検出しました。	エラーの説明を確認し、エラーが発生したファイルシステムオペレーションを特定します。オンプレミスエージェントがファイルシステムにアクセスし、基本的なファイルオペレーションに応答できるようにします。
Failed due to an unknown error	UNKNOWN_FAILURE	予期しないエラーが発生しました。	障害の説明を読みます。障害の説明に、問題解決に必要な情報が記載されていない場合は、サポートにお問い合わせください。
無効な仕様のため失敗しました	INVALID_SPEC	破損した内部仕様をエージェントが受信しました。	エージェントのホストでデータ破損を確認し、見つからない場合は、サポートまでお問い合わせください。
Failed due to an empty or invalid manifest file	CONFORMANCE_FAILURE	フォーマットまたは CSV エントリが無効であるため、エージェントは有効な CSV バイトの読み取りや取得ができません。	マニフェストエントリが有効なファイルパスであることを確認します。障害の説明に、問題解決に必要な情報が記載されていない場合は、サポートにお問い合わせください。
Falling back to resumable uploads instead of multipart uploads due to permission denied error	PERMISSION_FAILURE	この転送ではマルチパートアップロードが有効になっていますが、バケットに正しい権限が設定されていません。	必要な権限については、ファイルシステムの権限のマルチパートアップロードをご覧ください。

エージェントログの表示

エージェントログにはエージェントプロセスに関連する情報が記録されています。この情報は、エージェントの接続に関する問題のトラブルシューティングに役立ちます。Google Cloud Console でエージェントが接続済みと表示されていて、転送に失敗する場合は、エラーの表示で転送エラーのサンプルをご確認ください。転送中に Storage Transfer Service が処理したすべてのファイルが記録されているログを表示するには、転送ログの表示をご覧ください。

デフォルトでは、エージェントログは /tmp に保存されます。保存場所を変更するには、--log-dir=logs-directory コマンドラインオプションを使用します。

ログの名前は次のとおりです。

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

ここで

hostname - エージェントが実行されているホスト名。
username - エージェントを実行しているユーザー名。
log-level は次のいずれかです。
- INFO - 情報メッセージ。
- ERROR - 転送中にエラーが発生しましたが、転送ジョブを続行できます。
- FATAL - 転送ジョブの続行を妨げるエラーが発生しました。
timestamp - YYYYMMDD-hhmmss.thread-id 形式のタイムスタンプ。

logs ディレクトリには、各優先レベルの最新ログへのシンボリックリンクが含まれています。

agent.ERROR
agent.FATAL
agent.INFO

転送速度が遅い

データの転送に時間がかかる場合は、次の点をご確認ください。

ファイルシステムの読み取りスループットは、目的のアップロード速度の約 1.5 倍にしてください。FIO を使用して、ファイルシステムの読み取りスループットをテストできます。

fio をインストールします。
```
 sudo apt install -y fio
 
```
新しいディレクトリ fiotest を作成します。
```
 TEST_DIR=/mnt/mnt_dir/fiotest
 sudo mkdir -p $TEST_DIR
 
```
読み取りスループットをテストします。
```
 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
 
```
上記のコマンドを実行すると、Fio はレポートを生成します。「bw」というラベルの付いた行は、すべてのスレッドの集約帯域幅の合計を表し、読み取りスループットのプロキシとして使用できます。
iPerf3 を使用して、Storage Transfer Service で利用可能なインターネット帯域幅を確認します。
各転送エージェントに、少なくとも 4 個の vCPU と 8 GB の RAM があることを確認します。

上記の条件を満たしていても転送時間が長い場合は、エージェントを追加して、データのファイルシステムへの同時接続数を増やすことができます。

転送エージェントのパフォーマンスを最大化する方法については、エージェントのベストプラクティスをご覧ください。

エージェントエラーのトラブルシューティング

以降のセクションでは、転送エージェントのエラーのトラブルシューティングと解決方法について説明します。

エージェントが接続されていない

転送エージェントが Google Cloud コンソールで接続済みとして表示されない場合:

エージェントが Cloud Storage API に接続できることを確認します。
1. 転送エージェントと同じマシンから次のコマンドを実行して、エージェントと Cloud Storage API との接続をテストします。
  
  gsutil cp test.txt gs://my-bucket
  
  以下のように置き換えます。
  
  my-bucket: Cloud Storage バケットの名前。
プロジェクトで VPC Service Controls を使用している場合は、エージェントログを表示してエラーを確認します。VPC Service Controls の構成に誤りがあると、INFO エージェントログに次のエラーが記録されます。

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

この出力で:
- id は、VPC Service Controls エラーの一意の ID です。

エージェントは接続されているがジョブが失敗する

エージェントが接続済みとして表示されていても転送ジョブが失敗する場合は、失敗したジョブのエラーの詳細を確認します。

ファイル システム転送のトラブルシューティング

エラー

エージェント ログの表示