Storage Transfer Service のロギングを有効にする

このページでは、アクションと状態を記録するログデータを生成するように Storage Transfer Service を構成する方法について説明します。ログデータの表示と分析には、Cloud Logging を使用できます。

Storage Transfer Service は、すべての転送のログデータを生成できます。ただし、エージェント ベースの転送では、FIND オペレーションはログに記録されません。

ファイル システム転送では、ファイル システム転送ログを構成することもできます。

始める前に

始める前に、Cloud Logging にアクセスできることを確認してください。ログビューア(roles/logging.viewer)の Identity and Access Management ロールを使用することをおすすめします。Logging のアクセスの詳細については、IAM によるアクセス制御をご覧ください。

次のドキュメントでは、現在のアクセス権を確認する方法と IAM ロールを付与する方法について説明します。

ログに記録可能なアクション

ログに記録可能なアクションは次のとおりです。

  • FIND: 検索(ディレクトリ内のファイルの一覧表示、バケット内のオブジェクトの一覧表示、バケット内のマネージド フォルダの一覧表示など)。エージェント ベースの転送ではサポートされていません。
  • COPY: 宛先(Cloud Storage またはファイル システム)へのファイルまたはオブジェクトのコピー。
  • DELETE: ソースまたは宛先のファイルまたはオブジェクトの削除。 2 つのファイル システム間の転送では、中間の Cloud Storage バケットからのファイルの削除もログに記録されます。

ログに記録可能な状態

アクションごとに、次の状態を 1 つ以上記録することもできます。

  • SUCCEEDED: アクションは成功しました。
  • FAILED: アクションは失敗しました。
  • SKIPPED: COPY アクションにのみ適用され、エージェント ベースの転送ジョブでのみサポートされます。gcloud または REST API を使用して設定する必要があります。この状態は、コピーがスキップされたことを意味します。これは、ファイルがシンクにすでに存在し、既存のファイルを無視するように転送ジョブが構成されている場合に発生します。

ベスト プラクティス

FIND アクションまたは SUCCEEDED 状態のロギングを有効にすると、大量のログデータが生成される可能性があります。

保存されるログデータの量を減らすには、次の方法を使用できます。

  • 失敗のみをログに記録します。オブジェクト レベルの完全なコンプライアンス監査が必要ない場合は、コピーと削除のアクションのみ、かつエラーが発生した場合にのみログを書き込むようにジョブを構成します。

  • 指標データを使用して、スループット、バイト数、スキップされたオブジェクト、失敗したオブジェクトをモニタリングします。グラフを作成し、アラート ポリシーを使用して指標データをモニタリングできます。使用可能な指標の一覧については、転送ジョブをモニタリングするをご覧ください。

  • 価値の低い大量のログデータを破棄するように Cloud Logging を構成します。この変更を行うには、プロジェクトのログシンクを更新して、価値の低い Storage Transfer Service サービスログデータを除外します。プロジェクト内のすべてのログシンクがすべてのログエントリを評価するため、複数のログシンクを更新する必要がある場合があります。

    次の除外フィルタを使用して、成功したアクションを記録する Storage Transfer Service ログエントリを除外します。

    resource.type="storage_transfer_job" AND
    jsonPayload.status.statusCode="OK"
    

    ログシンクを検索して変更する方法については、サポートされている宛先にログを転送するをご覧ください。

ロギングを有効にする

ログデータを生成するように Storage Transfer Service を構成するには、ロギングの対象となるアクションと状態を指定します。

gcloud CLI

gcloud transfer jobs create を使用して転送ジョブを作成する際に、次のフラグを使用してロギングを有効にします。

gcloud transfer jobs create SOURCE DESTINATION \
  --log-actions=copy,delete \
  --log-action-states=succeeded,failed

それぞれのフラグに少なくとも 1 つの値を指定する必要があります。find を --log-actions に追加できるのはエージェントレス転送の場合のみです。skipped を --log-action-states に追加できるのはエージェント ベースの転送の場合のみです。この 2 つを同じジョブで組み合わせることはできません。

REST

ロギング構成を作成するには、LoggingConfig で transferJobs.create を使用します。

{
  "name": "transferJobs/myFirstTransfer",
  "status": "ENABLED",
  "projectId": "test-id-001",
  "loggingConfig": {
    "logActions": ["FIND", "DELETE", "COPY"],
    "logActionStates": ["SUCCEEDED", "FAILED"]
  },
  "transferSpec": {
    "gcsDataSource": {
      "bucketName": "source_bucket"
    },
    "gcsDataSink": {
      "bucketName": "destination_bucket",
      "path": "foo/bar/"
    }
  }
}

エージェント ベースの転送の場合は、logActions から "FIND" を省略します。必要に応じて、logActionStates に "SKIPPED" を含めることができます。

loggingConfig を編集して、ロギングする特定の logActions と logActionStates を指定します。たとえば、コピーと検索のアクションが失敗した場合にロギングするには、loggingConfig を次のように指定します。

"loggingConfig": {
  "logActions": ["COPY", "FIND"],
  "logActionStates": ["FAILED"]
}

ロギング構成を更新する

gcloud CLI

既存のジョブのロギング構成を更新するには、gcloud transfer jobs update コマンドを使用して目的のフラグを指定します。

gcloud transfer jobs update NAME \
  --log-actions=copy,delete \
  --log-action-states=succeeded,failed

このジョブのロギングを無効にするには、--clear-log-config を指定します。

gcloud transfer jobs update NAME --clear-log-config

REST

既存の転送ジョブのロギング構成を更新するには、transferJobs.patch を使用して LoggingConfig を指定します。

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
      "logActions": ["FIND", "DELETE", "COPY"],
      "logActionStates": ["SUCCEEDED", "FAILED"]
    }
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

updateTransferJobFieldMask は、このリクエストで更新されるフィールドを指定するもので、必須です。

このジョブのロギングを無効にするには、logActions と logActionStates に空のリストを指定して loggingConfig を送信します。

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
      "logActions": [],
      "logActionStates": []
    }
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

ログを表示

転送ログを表示する方法は次のとおりです。

Google Cloud コンソール

  1. Google Cloud ナビゲーション メニュー に移動し、[ロギング] > [ログ エクスプローラ] の順に選択します。

    [ログ エクスプローラ] に移動

  2. Google Cloud プロジェクトを選択します。

  3. ログをフィルタリングして Storage Transfer Service のエントリのみを表示するには、クエリ フィールドに「storage_transfer_job」と入力して [クエリを実行] をクリックします。

  4. [クエリ結果] ペインで [日時を編集する] をクリックし、結果を返す期間を変更します。

ログ エクスプローラの使用方法については、ログ エクスプローラの使用をご覧ください。

gcloud CLI

gcloud CLI を使用して Storage Transfer Service ログを検索するには、gcloud logging read コマンドを使用します。

結果を Storage Transfer Service のサービスログに限定するフィルタを指定します。

gcloud logging read "resource.type=storage_transfer_job"

Cloud Logging API

entries.list Cloud Logging API メソッドを使用します。

Storage Transfer Service 関連のエントリのみが含まれるように結果をフィルタするには、filter フィールドを使用します。JSON リクエスト オブジェクトのサンプルは次のとおりです。

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"storage_transfer_job\""
}

転送ログの形式

次のセクションに、Storage Transfer Service サービスログのフィールドを示します。

Storage Transfer Service 固有のフィールドはすべて、jsonPayload オブジェクトに格納されます。

FIND アクション

{
"jsonPayload": {
  "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
  "action": "FIND",
  "completeTime": "2021-12-16T18:58:49.344509695Z",
  "destinationContainer": {
    "gcsBucket": {
      "bucket": "my-bucket-2"
    },
    "type": "GCS"
  },
  "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
  "sourceContainer": {
    "gcsBucket": {
      "bucket": "my-bucket-1"
    },
    "type": "GCS"
  },
  "status": {
    "statusCode": "OK"
  }
}
}

COPY および DELETE アクション

{
"jsonPayload": {
  "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
  "action": "COPY",
  "completeTime": "2021-12-16T18:59:00.510509049Z",
  "destinationObject": {
    "gcsObject": {
      "bucket": "my-bucket-2",
      "objectKey": "README.md"
    },
    "type": "GCS"
  },
  "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
  "sourceObject": {
    "gcsObject": {
      "bucket": "my-bucket-1",
      "lastModifiedTime": "2021-12-07T16:41:09.456Z",
      "md5": "WgnCOIdfCXNTUDpQJSKb2w==",
      "objectKey": "README.md"
    },
    "type": "GCS"
  },
  "status": {
    "statusCode": "OK"
  }
}
}
ログフィールド 説明
@type 値は常に type.googleapis.com/google.storagetransfer.logging.TransferActivityLog です。
action

このタスクの操作を表します。次のいずれかです。

  • FIND: 検索(ディレクトリ内のファイルの一覧表示やバケット内のオブジェクトの一覧表示など)。エージェント ベースの転送では報告されません。
  • COPY: ファイルまたはオブジェクトを宛先(Cloud Storage またはファイル システム)にコピーします。
  • DELETE: 転送元バケット、転送先バケット、または中間バケットのファイルまたはオブジェクトの削除。
findAction

検索アクションの対象がオブジェクトかマネージド フォルダかを指定します。

completeTime オペレーションの完了時間を表す ISO 8601 準拠のタイムスタンプ。
destinationContainer

FIND オペレーションでのみ存在します。エージェント ベースの転送では、FIND オペレーションはログに記録されません。

この転送の転送先コンテナ。次の 2 つのサブフィールドがあります。

  • gcsBucket.bucket: 転送先の Cloud Storage のバケット名。
  • type: 常に GCS。
destinationObject

COPY および DELETE オペレーションの場合にのみ存在します。

転送先のオブジェクトに関する情報。次の 2 つのサブフィールドがあります。

  • 転送先に応じて、gcsObject、gcsManagedFolder、posixFile のいずれか。すべてのオプションには、名前、場所、日時情報、オブジェクトまたはファイルのハッシュを指定する複数のサブフィールドが含まれています。
  • type は、GCS か POSIX_FS のいずれかにします。

例:

"destinationObject": {
  "type": "POSIX_FS",
  "posixFile": {
    "crc32c": "0",
    "path": "/tmp/data/filename.txt",
    "lastModifiedTime": "2022-09-22T04:33:45Z"
  }
}
operation 完全修飾の transferOperations 名。
sourceContainer

FIND オペレーションでのみ存在します。エージェント ベースの転送では、FIND オペレーションはログに記録されません。

この転送のソースコンテナ。次の 2 つのサブフィールドがあります。

  • ソースの場所を指定するエントリ。このフィールドには、ソースの種類に応じて名前が付けられます。使用できるフィールドは次のとおりです。
    • awsS3Bucket.bucket: AWS S3 バケット名。
    • azureBlobContainer: account および container サブフィールドが含まれます。これらを組み合わせて、Microsoft Azure Blob ストレージ URI を定義します。
    • gcsBucket.bucket: Cloud Storage バケット名。
    • httpManifest.url: URL リストの URL。このリストには、HTTP(S) サーバーからダウンロードする一般公開ファイルを指定します。
  • type は、AWS_S3、AZURE_BLOB、GCS、または HTTP のいずれかです。

次に例を示します。

"sourceContainer": {
  "gcsBucket": {
    "bucket": "my-bucket-1"
  },
  "type": "GCS"
}
sourceObject

COPY および DELETE オペレーションの場合にのみ存在します。

ソース オブジェクトに関する情報。次の 2 つのサブフィールドがあります。

  • ソース オブジェクトのホスト固有のエントリ。このフィールドにはソースタイプに応じて名前が付けられます。メタデータ用のサブフィールドが含まれます。使用できるフィールドは次のとおりです。
    • awsS3Object: AWS S3 オブジェクト。
    • awsS3CompatibleObject: S3 互換ストレージ内のオブジェクト。
    • azureBlob: Azure Blob Storage 内のファイル。
    • gcsObject: Cloud Storage オブジェクト。
    • gcsManagedFolder: Cloud Storage マネージド フォルダ。
    • hdfsFile: HDFS 内のファイル。
    • httpFile: URL リストで指定されたファイル。
    • posixFile: POSIX ファイル システム上のファイル。
  • type は、AWS_S3、AWS_S3_COMPATIBLE、AZURE_BLOB、GCS、HDFS、HTTP、POSIX_FS のいずれかです。

次に例を示します。

"sourceObject": {
  "gcsObject": {
    "bucket": "my-bucket-1",
    "lastModifiedTime": "2021-12-07T16:41:09.456Z",
    "md5": "WgnCOIdfCXNTUDpQJSKb2w==",
    "objectKey": "README.md"
  },
  "type": "GCS"
}
status

アクションのステータス。status.statusCode が OK である場合、アクションは成功しています。それ以外の場合、アクションは失敗しています。status.errorType フィールドと status.errorMessage フィールドは、ステータスが OK でない場合にのみ入力されます。

また、最上位の resource フィールドには以下のフィールドが含まれます。

"resource": {
  "labels": {
    "job_id": "transferJobs/7876027868280507149",
    "project_id": "my-project-id"
  },
  "type": "storage_transfer_job"
}
ログフィールド 説明
resource.labels.job_id このログが属する Storage Transfer Service のジョブ名。
resource.labels.project_id この転送の Google Cloud プロジェクト ID。