为 Storage Transfer Service 启用日志记录

本页面介绍了如何配置 Storage Transfer Service 以生成记录操作和状态的日志数据。您可以使用 Cloud Logging 查看和分析日志数据。

Storage Transfer Service 可以为所有转移作业生成日志数据。不过，对于基于代理的转移作业，系统不会记录 FIND 操作。

文件系统转移作业还可以配置 文件系统转移日志。

准备工作

在开始之前，请验证您是否有权访问 Cloud Logging。我们建议使用 Logs Viewer (roles/logging.viewer) Identity and Access Management 角色。如需详细了解 Logging 访问权限，请参阅使用 IAM 进行访问权限控制。

以下文档介绍了如何验证当前访问权限以及如何授予 IAM 角色：

• 查看当前访问权限 以验证每个主账号具有的访问权限。
• 向项目中的相关主账号授予角色。

可记录的操作

可以记录以下操作：

• FIND：查找待办事项，例如列出目录中的文件、列出存储桶中的对象或列出存储桶中的托管文件夹。基于代理的转移作业不支持此操作。
• COPY：将文件或对象复制到 Cloud Storage。
• DELETE：删除来源或目标位置的文件或对象。对于在两个文件系统之间进行的转移作业，系统还会记录从中间 Cloud Storage 存储桶中删除文件的操作。

可记录的状态

对于每项操作，您还可以记录以下一个或多个状态：

• SUCCEEDED：操作成功。
• FAILED：操作失败。
• SKIPPED：仅适用于 COPY 操作，且仅支持基于代理的转移作业。必须使用 gcloud 或 REST API 进行设置。此状态表示复制操作已跳过。如果文件已存在于接收器中，并且您的转移作业配置为忽略现有文件，则会发生这种情况。

最佳做法

为 FIND 操作或为 SUCCEEDED 状态启用日志记录可能会 导致日志数据量过大，这可能会影响您的 Cloud Logging 费用。

您可以使用以下策略来减少存储的日志数据量：

• 仅记录失败。如果您不需要完整的对象级合规性审核，请将作业配置为仅针对复制和删除操作写入日志，并且仅在发生失败时写入日志。

• 使用指标数据监控吞吐量、字节数以及跳过或失败的对象。您可以创建图表， 也可以使用提醒政策监控指标数据。 如需查看可用指标的列表，请参阅 Storage Transfer Service。

• 将 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,find \
  --log-action-states=succeeded,failed,skipped

您必须为每个标志至少指定一个值。

REST

如需创建日志记录配置，请使用带有 LoggingConfig 的 transferJobs.create：

{
  "name":"transferJobs/myFirstTransfer",
  "status": "ENABLED",
  "projectId": "test-id-001",
  "loggingConfig": {
     "logActions": ["FIND", "DELETE", "COPY"],
     "logActionStates": ["SUCCEEDED", "FAILED", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
  },
  "transferSpec": {
      "awsS3DataSource": {
          "bucketName": "AWS_SOURCE_NAME",
          "awsAccessKey": {
              "accessKeyId": "AWS_ACCESS_KEY_ID",
              "secretAccessKey": "AWS_SECRET_ACCESS_KEY"
          }
      },
      "gcsDataSink": {
           "bucketName": "destination_bucket",
           "path": "foo/bar/"
      },
   }
}

调整 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,find \
  --log-action-states=succeeded,failed,skipped

如需停用此作业的日志记录，请指定 --clear-log-config：

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

REST

如需更新现有转移作业的日志记录配置，请使用 transferJobs.patch with LoggingConfig：

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
       "logActions": ["FIND", "DELETE", "COPY"],
       "logActionStates": ["SUCCEEDED", "FAILED", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
    },
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

updateTransferJobFieldMask 指定此请求中要更新的字段，并且此字段为必填字段。

如需停用此作业的日志记录，请发送 loggingConfig 以及 logActions 和 logActionStates 的空列表：

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

查看日志

如需查看转移日志，请执行以下操作：

Google Cloud 控制台

1. 转到 Google Cloud 导航菜单 ，然后选择 Logging > 日志浏览器 :
   

   转到 Logs Explorer

2. 选择一个 Google Cloud 项目。

3. 在升级 菜单中，从旧版日志查看器 切换到Logs Explorer 。

4. 如需过滤日志以仅显示 Storage Transfer Service 条目，请在查询字段中输入 storage_transfer_job，然后点击运行查询。

5. 在查询结果窗格中，点击修改时间以更改返回结果的时间段。

如需详细了解如何使用 Logs Explorer，请参阅 使用 Logs Explorer。

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 操作不会记录在基于代理的转移作业中。 此转移作业的目标容器。包含两个 子字段： gcsBucket.bucket：目标 Cloud Storage 存储桶名称。 type：始终为 GCS。
destinationObject	仅适用于 COPY 和 DELETE 操作。 与目标位置的对象相关的信息。包含两个 子字段： 根据目标位置，可以是 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 操作不会记录在基于代理的转移作业中。 此转移的来源容器。包含两个子字段： 指定来源位置的条目。该字段根据来源类型命名。可能的字段如下所示。 awsS3Bucket.bucket：AWS S3 存储桶名称。 azureBlobContainer：包含 account 和 container 子字段，它们共同定义 Microsoft Azure Blob 存储 URI。 gcsBucket.bucket：Cloud Storage 存储桶名称。 httpManifest.url：网址列表的网址。该网址指定了要从 HTTP(S) 服务器下载的公开提供的文件。 type 是 AWS_S3、AZURE_BLOB、GCS 或 HTTP 中的一个。 例如： "sourceContainer": { "gcsBucket": { "bucket": "my-bucket-1" }, type: "GCS" }
sourceObject	仅适用于 COPY 和 DELETE 操作。 与源对象相关的信息。包含两个子字段： 特定于来源对象的主机的条目。该字段根据来源类型命名，并包含元数据的子字段。可能的字段如下所示。 awsS3Object：AWS S3 对象。 azureBlob：Azure Blob Storage 中的文件。 gcsObject：Cloud Storage 对象。 gcsManagedFolder：Cloud Storage 托管 文件夹。 httpFile：由 网址列表指定的文件。 posixFile：POSIX 文件系统上的文件。 type 是 AWS_S3、AZURE_BLOB、GCS、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，则表示操作成功。否则，操作失败。仅当状态不是 OK 时，才会填充 status.errorType 和 status.errorMessage 字段。

此外，顶级 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。