Creating your DataSync task reports
AWS DataSync task reports can be only a summary of your task execution or a set of detailed reports about what DataSync attempts to transfer, skip, verify, and delete.
Prerequisites
Before you can create a task report, you must do the following.
Topics
Create an S3 bucket for your task reports
If you don't already have one, create an S3 bucket where DataSync can upload your task report. Reports are stored in the S3 Standard storage class.
We recommend the following for this bucket:
-
If you're planning to transfer data to an S3 bucket, don't use the same bucket for your task report if you disable the Keep deleted files option. Otherwise, DataSync will delete any previous task reports each time you execute a task since those reports don't exist in your source location.
-
To avoid a complex access permissions setup, make sure that your task report bucket is in the same AWS account and Region as your DataSync transfer task.
Allow DataSync to upload task reports to your S3 bucket
You must configure an AWS Identity and Access Management (IAM) role that allows DataSync to upload a task report to your S3 bucket.
In the DataSync console, you can create an IAM role that in most cases automatically includes the permissions to upload a task report to your bucket. Keep in mind that this automatically generated role might not meet your needs from a least-privilege standpoint. This role also won't work if your bucket is encrypted with a customer managed AWS Key Management Service (AWS KMS) key (SSE-KMS). In these cases, you can create the role manually as long as the role does at least the following:
-
Prevents the cross-service confused deputy problem in the role's trusted entity.
The following full example shows how you can use the
aws:SourceArn
andaws:SourceAccount
global condition context keys to prevent the confused deputy problem with DataSync.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "datasync.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "
123456789012
" }, "StringLike": { "aws:SourceArn": "arn:aws:datasync:us-east-2
:123456789012
:*" } } } ] } -
Allows DataSync to upload a task report to your S3 bucket.
The following example does this by including the
s3:PutObject
action only for a specific prefix (reports/
) in your bucket.{ "Version": "2012-10-17", "Statement": [{ "Action": [ "s3:PutObject" ], "Effect": "Allow", "Resource": "arn:aws:s3:::
your-task-reports-bucket
/reports/*" }] } -
If your S3 bucket is encrypted with a customer managed SSE-KMS key, the key's policy must include the IAM role that DataSync uses to access the bucket.
For more information, see Accessing S3 buckets using server-side encryption.
Creating a summary only task report
You can configure a task report that includes a summary only when creating your DataSync task, starting your task, or updating your task.
The following steps show how to configure a summary only task report when creating a task.
Open the AWS DataSync console at https://console.aws.amazon.com/datasync/
. In the left navigation pane, expand Data transfer, then choose Tasks, and then choose Create task.
-
Configure your task's source and destination locations.
For more information, see Where can I transfer my data with AWS DataSync?
-
Scroll down to the Task report section. For Report type, choose Summary only.
-
For S3 bucket for reports, choose an S3 bucket where you want DataSync to upload your task report.
Tip
If you're planning to transfer data to an S3 bucket, don't use the same bucket for your task report if you disable the Keep deleted files option. Otherwise, DataSync will delete any previous task reports each time you execute a task since those reports don't exist in your source location.
-
For Folder, enter a prefix to use for your task report when DataSync uploads the report to your S3 bucket (for example,
reports/
).Make sure to include the appropriate delimiter character at the end of your prefix. This character is usually a forward slash (
/
). For more information, see Organizing objects by using prefixes in the Amazon S3 User Guide. -
For IAM role, do one of the following:
-
Choose Autogenerate to have DataSync automatically create an IAM role with the permissions that are required to access the S3 bucket.
If DataSync previously created an IAM role for this S3 bucket, that role is chosen by default.
-
Choose a custom IAM role that you created.
In some cases, you might need to create the role yourself. For more information, see Allow DataSync to upload task reports to your S3 bucket.
Important
If your S3 bucket is encrypted with a customer managed SSE-KMS key, the key's policy must include the IAM role that DataSync uses to access the bucket.
For more information, see Accessing S3 buckets using server-side encryption.
-
-
Finish creating your task, and then start the task to begin transferring your data.
When your transfer is complete, you can view your task report.
-
Copy the following
create-task
AWS Command Line Interface (AWS CLI) command:aws datasync create-task \ --source-location-arn arn:aws:datasync:
us-east-1
:123456789012
:location/loc-12345678abcdefgh
\ --destination-location-arn arn:aws:datasync:us-east-1
:123456789012
:location/loc-abcdefgh12345678
\ --task-report-config '{ "Destination":{ "S3":{ "Subdirectory":"reports/
", "S3BucketArn":"arn:aws:s3:::your-task-reports-bucket
", "BucketAccessRoleArn":"arn:aws:iam::123456789012
:role/bucket-iam-role
" } }, "OutputType":"SUMMARY_ONLY" }' -
For the
--source-location-arn
parameter, specify the Amazon Resource Name (ARN) of the source location in your transfer. Replace
with the appropriate AWS Region, replaceus-east-1
with the appropriate AWS account number, and replace123456789012
with the appropriate source location ID.12345678abcdefgh
-
For the
--destination-location-arn
parameter, specify the ARN of the destination location in your transfer. Replace
with the appropriate AWS Region, replaceus-east-1
with the appropriate AWS account number, and replace123456789012
with the appropriate destination location ID.abcdefgh12345678
-
For the
--task-report-config
parameter, do the following:-
Subdirectory
– Replace
with the prefix in your S3 bucket where you want DataSync to upload your task reports.reports/
Make sure to include the appropriate delimiter character at the end of your prefix. This character is usually a forward slash (
/
). For more information, see Organizing objects by using prefixes in the Amazon S3 User Guide. -
S3BucketArn
– Specify the ARN of the S3 bucket where you want to upload your task report.Tip
If you're planning to transfer data to an S3 bucket, don't use the same bucket for your task report if you disable the Keep deleted files option. Otherwise, DataSync will delete any previous task reports each time you execute a task since those reports don't exist in your source location.
-
BucketAccessRoleArn
– Specify the IAM role that allows DataSync to upload a task report to your S3 bucket.For more information, see Allow DataSync to upload task reports to your S3 bucket.
Important
If your S3 bucket is encrypted with a customer managed SSE-KMS key, the key's policy must include the IAM role that DataSync uses to access the bucket.
For more information, see Accessing S3 buckets using server-side encryption.
-
OutputType
– SpecifySUMMARY_ONLY
.For more information, see Summary only task reports.
-
-
Run the
create-task
command to create your task.You get a response like the following that shows you the ARN of the task that you created. You will need this ARN to run the
start-task-execution
command.{ "TaskArn": "arn:aws:datasync:us-east-1:123456789012:task/task-12345678abcdefgh" }
-
Copy the following
start-task-execution
command.aws datasync-task-report start-task-execution \ --task-arn arn:aws:datasync:
us-east-1
:123456789012
:task/task-12345678abcdefgh
-
For the
--task-arn
parameter, specify the ARN of the task that you're starting. Use the ARN that you received from running thecreate-task
command. -
Run the
start-task-execution
command.
When your transfer is complete, you can view your task report.
Creating a standard task report
You can configure a standard task report when creating your DataSync task, starting your task, or updating your task.
The following steps show how to configure a standard task report when creating a task.
Open the AWS DataSync console at https://console.aws.amazon.com/datasync/
. In the left navigation pane, expand Data transfer, then choose Tasks, and then choose Create task.
-
Configure your task's source and destination locations.
For more information, see Where can I transfer my data with AWS DataSync?
-
Scroll down to the Task report section. For Report type, choose Standard report.
-
For Report level, choose one of the following:
-
Errors only – Your task report includes only issues with what DataSync tried to transfer, skip, verify, and delete.
-
Successes and errors – Your task report includes what DataSync successfully transferred, skipped, verified, and deleted and what it didn't.
-
Custom – Allows you to choose whether you want to see errors only or successes and errors for specific aspects of your task report.
For example, you can choose Successes and errors for the transferred files list but Errors only for the rest of the report.
-
-
If you're transferring to an S3 bucket that uses object versioning, keep Include Amazon S3 object versions selected if you want your report to include the new version for each transferred object.
-
For S3 bucket for reports, choose an S3 bucket where you want DataSync to upload your task report.
Tip
If you're planning to transfer data to an S3 bucket, don't use the same bucket for your task report if you disable the Keep deleted files option. Otherwise, DataSync will delete any previous task reports each time you execute a task since those reports don't exist in your source location.
-
For Folder, enter a prefix to use for your task report when DataSync uploads the report to your S3 bucket (for example,
reports/
). Make sure to include the appropriate delimiter character at the end of your prefix. This character is usually a forward slash (/
). For more information, see Organizing objects by using prefixes in the Amazon S3 User Guide. -
For IAM role, do one of the following:
-
Choose Autogenerate to have DataSync automatically create an IAM role with the permissions that are required to access the S3 bucket.
If DataSync previously created an IAM role for this S3 bucket, that role is chosen by default.
-
Choose a custom IAM role that you created.
In some cases, you might need to create the role yourself. For more information, see Allow DataSync to upload task reports to your S3 bucket.
Important
If your S3 bucket is encrypted with a customer managed SSE-KMS key, the key's policy must include the IAM role that DataSync uses to access the bucket.
For more information, see Accessing S3 buckets using server-side encryption.
-
-
Finish creating your task and start the task to begin transferring your data.
When your transfer is complete, you can view your task report.
-
Copy the following
create-task
command:aws datasync create-task \ --source-location-arn arn:aws:datasync:
us-east-1
:123456789012
:location/loc-12345678abcdefgh
\ --destination-location-arn arn:aws:datasync:us-east-1
:123456789012
:location/loc-abcdefgh12345678
\ --task-report-config '{ "Destination":{ "S3":{ "Subdirectory":"reports/
", "S3BucketArn":"arn:aws:s3:::your-task-reports-bucket
", "BucketAccessRoleArn":"arn:aws:iam::123456789012
:role/bucket-iam-role
" } }, "OutputType":"STANDARD", "ReportLevel":"level-of-detail
", "ObjectVersionIds":"include-or-not
" }' -
For the
--source-location-arn
parameter, specify the ARN of the source location in your transfer. Replace
with the appropriate AWS Region, replaceus-east-1
with the appropriate AWS account number, and replace123456789012
with the appropriate source location ID.12345678abcdefgh
-
For the
--destination-location-arn
parameter, specify the ARN of the destination location in your transfer. Replace
with the appropriate AWS Region, replaceus-east-1
with the appropriate AWS account number, and replace123456789012
with the appropriate destination location ID.abcdefgh12345678
-
For the
--task-report-config
parameter, do the following:-
Subdirectory
– Replace
with the prefix in your S3 bucket where you want DataSync to upload your task reports. Make sure to include the appropriate delimiter character at the end of your prefix. This character is usually a forward slash (reports/
/
). For more information, see Organizing objects by using prefixes in the Amazon S3 User Guide. -
S3BucketArn
– Specify the ARN of the S3 bucket where you want to upload your task report.Tip
If you're planning to transfer data to an S3 bucket, don't use the same bucket for your task report if you disable the Keep deleted files option. Otherwise, DataSync will delete any previous task reports each time you execute a task since those reports don't exist in your source location.
-
BucketAccessRoleArn
– Specify the IAM role that allows DataSync to upload a task report to your S3 bucket.For more information, see Allow DataSync to upload task reports to your S3 bucket.
Important
If your S3 bucket is encrypted with a customer managed SSE-KMS key, the key's policy must include the IAM role that DataSync uses to access the bucket.
For more information, see Accessing S3 buckets using server-side encryption.
-
OutputType
– SpecifySTANDARD
report.For more information, see Standard task reportsTypes of task reports.
-
(Optional)
ReportLevel
– Specify whether you wantERRORS_ONLY
(the default) orSUCCESSES_AND_ERRORS
in your report. -
(Optional)
ObjectVersionIds
– If you're transferring to an S3 bucket that uses object versioning, specifyNONE
if you don't want to include the new version for each transferred object in the report.By default, this option is set to
INCLUDE
. -
(Optional)
Overrides
– Customize theReportLevel
of a particular aspect of your report.For example, you might want to see
SUCCESSES_AND_ERRORS
for the list of what DataSync deletes in your destination location, but you wantERRORS_ONLY
for everything else. In this example, you would add the followingOverrides
option to the--task-report-config
parameter:"Overrides":{ "Deleted":{ "ReportLevel":"SUCCESSES_AND_ERRORS" } }
If you don't use
Overrides
, your entire report uses theReportLevel
that you specify.
-
-
Run the
create-task
command to create your task.You get a response like the following that shows you the ARN of the task that you created. You will need this ARN to run the
start-task-execution
command.{ "TaskArn": "arn:aws:datasync:us-east-1:123456789012:task/task-12345678abcdefgh" }
-
Copy the following
start-task-execution
command.aws datasync-task-report start-task-execution \ --task-arn arn:aws:datasync:
us-east-1
:123456789012
:task/task-12345678abcdefgh
-
For the
--task-arn
parameter, specify the ARN of the task you're running. Use the ARN that you received from running thecreate-task
command. -
Run the
start-task-execution
command.
When your transfer is complete, you can view your task report.