为 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:删除来源或目标位置的文件或对象。对于两个文件系统之间的转移作业,还会记录从中间 Cloud Storage 存储桶中删除文件的操作。

可记录的状态

对于每项操作,您还可以记录以下一种或多种状态:

  • 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

您必须为每个标志至少指定一个值。您只能为无代理转移作业添加 find 到 --log-actions,只能为基于代理的转移作业添加 skipped 到 --log-action-states;两者不能在同一作业中组合使用。

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

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

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

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

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

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

查看日志

如需查看转移日志,请执行以下操作:

Google Cloud 控制台

  1. 前往 Google Cloud 导航菜单 ,然后选择 Logging > Logs Explorer:

    前往 Logs Explorer

  2. 选择一个 Google Cloud 项目。

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

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

如需详细了解如何使用 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 对象。
    • awsS3CompatibleObject:与 S3 兼容的存储空间中的对象。
    • azureBlob:Azure Blob Storage 中的文件。
    • gcsObject:Cloud Storage 对象。
    • gcsManagedFolder:Cloud Storage 代管式文件夹。
    • hdfsFile:HDFS 中的文件。
    • httpFile:由网址列表指定的文件。
    • 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,则表示操作成功。否则,操作失败。仅当状态不是 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。