# Monitoring replication with metrics, event notifications, and statuses
You can monitor your live replication configurations and your S3 Batch Replication jobs through the following mechanisms:
+ **S3 Replication metrics** – When you enable S3 Replication metrics, Amazon CloudWatch emits metrics that you can use to track bytes pending, operations pending, and replication latency at the replication rule level. You can view S3 Replication metrics through the Amazon S3 console and the Amazon CloudWatch console. In the Amazon S3 console, you can view these metrics in the source bucket's **Metrics** tab. For more information about S3 Replication metrics, see [Using S3 Replication metrics](repl-metrics.md).
+ **S3 Storage Lens metrics** – In addition to S3 Replication metrics, you can use the replication-related Data Protection metrics provided by S3 Storage Lens dashboards. For example, if you use the free metrics in S3 Storage Lens, you can see metrics such as the total number of bytes that are replicated from the source bucket or the count of replicated objects from the source bucket.
To audit your overall replication stance, you can enable advanced metrics in S3 Storage Lens. With advanced metrics in S3 Storage Lens, you can see how many replication rules you have of various types, including the count of replication rules with a replication destination that's not valid.
For more information about working with replication metrics in S3 Storage Lens, see [Viewing replication metrics in S3 Storage Lens dashboards](viewing-replication-metrics-storage-lens.md).
+ **S3 Event Notifications** – S3 Event Notifications can notify you at the object level in instances when objects don't replicate to their destination AWS Region or when objects aren't replicated within certain thresholds. S3 Event Notifications provides the following replication event types: `s3:Replication:OperationFailedReplication`, `s3:Replication:OperationMissedThreshold`, `s3:Replication:OperationReplicatedAfterThreshold`, and `s3:Replication:OperationNotTracked`.
Amazon S3 events are available through Amazon Simple Queue Service (Amazon SQS), Amazon Simple Notification Service (Amazon SNS), or AWS Lambda. For more information, see [Receiving replication failure events with Amazon S3 Event Notifications](replication-metrics-events.md).
+ **Replication status values** – You can also retrieve the replication status of your objects. The replication status can help you determine the current state of an object that's being replicated. The replication status of a source object will return either `PENDING`, `COMPLETED`, or `FAILED`. The replication status of a replica will return `REPLICA`.
You can also use replication status values when you're creating S3 Batch Replication jobs. For example, you can use these status values to replicate objects that have either never been replicated or that have failed replication.
For more information about retrieving the replication status of your objects, see [Getting replication status information](replication-status.md). For more information about using these values with Batch Replication, see [Filters for a Batch Replication job](s3-batch-replication-batch.md#batch-replication-filters).
**Topics**
+ [
# Using S3 Replication metrics
](repl-metrics.md)
+ [
# Viewing replication metrics in S3 Storage Lens dashboards
](viewing-replication-metrics-storage-lens.md)
+ [
# Receiving replication failure events with Amazon S3 Event Notifications
](replication-metrics-events.md)
+ [
# Getting replication status information
](replication-status.md)
# Using S3 Replication metrics
S3 Replication metrics provide detailed metrics for the replication rules in your replication configuration. With replication metrics, you can monitor minute-by-minute progress by tracking bytes pending, operations pending, operations that failed replication, and replication latency.
**Note**
S3 Replication metrics are billed at the same rate as Amazon CloudWatch custom metrics. For more information, see [Amazon CloudWatch pricing](https://aws.amazon.com/cloudwatch/pricing/).
If you're using S3 Replication Time Control, Amazon CloudWatch begins reporting replication metrics 15 minutes after you enable S3 RTC on the respective replication rule.
S3 Replication metrics are turned on automatically when you enable S3 Replication Time Control (S3 RTC). You can also enable S3 Replication metrics independently of S3 RTC while [ creating or editing a rule](replication-walkthrough1.md). S3 RTC includes other features, such as a service level agreement (SLA) and notifications for missed thresholds. For more information, see [Meeting compliance requirements with S3 Replication Time Control](replication-time-control.md).
When S3 Replication metrics are enabled, Amazon S3 publishes the following metrics to Amazon CloudWatch. CloudWatch metrics are delivered on a best-effort basis.
| Metric name | Metric description | Which objects does this metric apply to? | Which Region is this metric published in? | Is this metric still published if the destination bucket is deleted? | Is this metric still published if replication doesn't occur? |
| --- | --- | --- | --- | --- | --- |
| **Bytes Pending Replication** | The total number of bytes of objects that are pending replication for a given replication rule. | This metric applies only to new objects that are replicated with S3 Cross-Region Replication (S3 CRR) or S3 Same-Region Replication (S3 SRR). | This metric is published in the Region of the destination bucket. | No | Yes |
| **Replication Latency** | The maximum number of seconds by which the replication destination bucket is behind the source bucket for a given replication rule. | This metric applies only to new objects that are replicated with S3 CRR or S3 SRR. | This metric is published in the Region of the destination bucket. | No | Yes |
| **Operations Pending Replication** | The number of operations that are pending replication for a given replication rule. This metric tracks operations related to objects, delete markers, tags, access control lists (ACLs), and S3 Object Lock. | This metric applies only to new objects that are replicated with S3 CRR or S3 SRR. | This metric is published in the Region of the destination bucket. | No | Yes |
| **Operations Failed Replication** | The number of operations that failed replication for a given replication rule. This metric tracks operations related to objects, delete markers, tags, access control lists (ACLs), and Object Lock. **Operations Failed Replication** tracks S3 Replication failures aggregated at a per-minute interval. To identify the specific objects that have failed replication and their failure reasons, subscribe to the `OperationFailedReplication` event in Amazon S3 Event Notifications. For more information, see [Receiving replication failure events with Amazon S3 Event Notifications](replication-metrics-events.md). | This metric applies both to new objects that are replicated with S3 CRR or S3 SRR and also to existing objects that are replicated with S3 Batch Replication. If an S3 Batch Replication job fails to run at all, metrics aren't sent to Amazon CloudWatch. For example, your job won't run if you don't have the necessary permissions to run an S3 Batch Replication job, or if the tags or prefix in your replication configuration don't match. | This metric is published in the Region of the source bucket. | Yes | No |
For information about working with these metrics in CloudWatch, see [S3 Replication metrics in CloudWatch](metrics-dimensions.md#s3-cloudwatch-replication-metrics).
## Enabling S3 Replication metrics
You can start using S3 Replication metrics with a new or existing replication rule. For full instructions on creating replication rules, see [Configuring replication for buckets in the same account](replication-walkthrough1.md). You can choose to apply your replication rule to an entire S3 bucket, or to Amazon S3 objects with a specific prefix or tag.
This topic provides instructions for enabling S3 Replication metrics in your replication configuration when the source and destination buckets are owned by the same or different AWS accounts.
To enable replication metrics by using the AWS Command Line Interface (AWS CLI), you must add a replication configuration to the source bucket with `Metrics` enabled. In this example configuration, objects under the prefix `Tax` are replicated to the destination bucket `amzn-s3-demo-bucket`, and metrics are generated for those objects.
```
{
"Rules": [
{
"Status": "Enabled",
"Filter": {
"Prefix": "Tax"
},
"Destination": {
"Bucket": "arn:aws:s3:::amzn-s3-demo-bucket",
"Metrics": {
"Status": "Enabled"
}
},
"Priority": 1
}
],
"Role": "IAM-Role-ARN"
}
```
## Viewing replication metrics
You can view S3 Replication metrics in the source general purpose bucket's **Metrics** tab in the Amazon S3 console. These Amazon CloudWatch metrics are also available in the Amazon CloudWatch console. When you enable S3 Replication metrics, Amazon CloudWatch emits metrics that you can use to track bytes pending, operations pending, and replication latency at the replication rule level.
S3 Replication metrics are turned on automatically when you enable replication with S3 Replication Time Control (S3 RTC) by using the Amazon S3 console or the Amazon S3 REST API. You can also enable S3 Replication metrics independently of S3 RTC while [ creating or editing a rule](replication-walkthrough1.md).
If you're using S3 Replication Time Control, Amazon CloudWatch begins reporting replication metrics 15 minutes after you enable S3 RTC on the respective replication rule. For more information, see [Using S3 Replication metrics](#repl-metrics).
Replication metrics track the rule IDs of the replication configuration. A replication rule ID can be specific to a prefix, a tag, or a combination of both.
For more information about CloudWatch metrics for Amazon S3, see [Monitoring metrics with Amazon CloudWatch](cloudwatch-monitoring.md).
**Prerequisites**
Create a replication rule that has S3 Replication metrics enabled. For more information, see [Enabling S3 Replication metrics](#enabling-replication-metrics).
**To view S3 Replication metrics through the source bucket's **Metrics** tab**
1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. In the left navigation pane, choose **General purpose buckets**.
1. In the buckets list, choose the name of the source bucket that contains the objects that you want replication metrics for.
1. Choose the **Metrics** tab.
1. Under **Replication metrics**, choose the replication rules that you want to see metrics for.
1. Choose **Display charts**.
Amazon S3 displays **Replication latency**, **Bytes pending replication**, **Operations pending replication**, and **Operations failed replication** charts for the rules that you selected.
# Viewing replication metrics in S3 Storage Lens dashboards
In addition to [S3 Replication metrics](repl-metrics.md), you can use the replication-related Data Protection metrics provided by S3 Storage Lens. S3 Storage Lens is a cloud-storage analytics feature that you can use to gain organization-wide visibility into object-storage usage and activity. For more information, see [Using S3 Storage Lens to protect your data](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-lens-data-protection.html#storage-lens-data-protection-replication-rule).
S3 Storage Lens has two tiers of metrics: free metrics, and advanced metrics and recommendations, which you can upgrade to for an additional charge. With advanced metrics and recommendations, you can access additional metrics and features for gaining insight into your storage. For information about S3 Storage Lens pricing, see [Amazon S3 pricing](https://aws.amazon.com/s3/pricing).
If you use the free metrics in S3 Storage Lens, you can see metrics such as the total number of bytes that are replicated from the source bucket or the count of replicated objects from the source bucket.
To audit your overall replication stance, you can enable advanced metrics in S3 Storage Lens. With advanced metrics in S3 Storage Lens, you can see how many replication rules you have of various types, including the count of replication rules with a replication destination that's not valid.
For a complete list of S3 Storage Lens metrics, including which replication metrics are in each tier, see the [S3 Storage Lens metrics glossary](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage_lens_metrics_glossary.html?icmpid=docs_s3_user_guide_replication.html).
**Prerequisites**
Create a [live replication configuration](replication-how-setup.md) or an [S3 Batch Replication job](s3-batch-replication-batch.md).
**To view replication metrics in Amazon S3 Storage Lens**
1. Create an S3 Storage Lens dashboard. For step-by-step instructions, see [Using the S3 console](storage_lens_creating_dashboard.md#storage_lens_console_creating).
1. (Optional) During your dashboard setup, if you want to see all S3 Storage Lens replication metrics, select **Advanced metrics and recommendations** and then select **Advanced data protection metrics**. For a complete list of metrics, see the [S3 Storage Lens metrics glossary](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage_lens_metrics_glossary.html?icmpid=docs_s3_user_guide_replication.html).
If you enable advanced metrics and recommendations, you can gain further insights into your replication configurations. For example, you can use S3 Storage Lens replication rule count metrics to get detailed information about your buckets that are configured for replication. This information includes replication rules within and across buckets and Regions. For more information, see [Count the total number of replication rules for each bucket](storage-lens-data-protection.md#storage-lens-data-protection-replication-rule).
1. After you've created your dashboard, open the dashboard, and choose the **Buckets** tab.
1. Scroll down to the **Buckets** section. Under **Metrics categories**, choose **Data protection**. Then clear **Summary**.
1. To filter the **Buckets** list to display only replication metrics, choose the preferences icon (![\[The preferences icon in the S3 Storage Lens dashboard.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/preferences.png)).
1. Clear the toggles for all data-protection metrics until only the replication metrics remain selected.
1. (Optional) Under **Page size**, choose the number of buckets to display in the list.
1. Choose **Continue**.
# Receiving replication failure events with Amazon S3 Event Notifications
If you've enabled S3 Replication metrics on your replication configuration, you can set up Amazon S3 Event Notifications to notify you when objects don't replicate to their destination AWS Region. If you've enabled S3 Replication Time Control (S3 RTC) on your replication configuration, you can also be notified when objects don't replicate within the 15-minute S3 RTC threshold for replication.
By using the following `Replication` event types, you can monitor the minute-by-minute progress of replication events by tracking bytes pending, operations pending, and replication latency. For more information about S3 Replication metrics, see [Using S3 Replication metrics](repl-metrics.md).
+ The `s3:Replication:OperationFailedReplication` event type notifies you when an object that was eligible for replication failed to replicate.
+ The `s3:Replication:OperationMissedThreshold` event type notifies you when an object that was eligible for replication that uses S3 RTC exceeds the 15-minute threshold for replication.
+ The `s3:Replication:OperationReplicatedAfterThreshold` event type notifies you when an object that was eligible for replication that uses S3 RTC replicates after the 15-minute threshold.
+ The `s3:Replication:OperationNotTracked` event type notifies you when an object that was eligible for live replication (either Same-Region Replication [SRR] or Cross-Region Replication [CRR]) is no longer being tracked by replication metrics.
For full descriptions of all the supported replication event types, see [Supported event types for SQS, SNS, and Lambda](notification-how-to-event-types-and-destinations.md#supported-notification-event-types).
For a list of the failure codes captured by S3 Event Notifications, see [Amazon S3 replication failure reasons](#replication-failure-codes).
You can receive S3 Event Notifications through Amazon Simple Queue Service (Amazon SQS), Amazon Simple Notification Service (Amazon SNS), or AWS Lambda. For more information, see [Amazon S3 Event Notifications](EventNotifications.md).
For instructions on how to configure Amazon S3 Event Notifications, see [Enabling event notifications](how-to-enable-disable-notification-intro.md).
**Note**
In addition to enabling event notifications, make sure that you also enable S3 Replication metrics. For more information, see [Enabling S3 Replication metrics](repl-metrics.md#enabling-replication-metrics).
The following is an example of a message that Amazon S3 sends to publish an `s3:Replication:OperationFailedReplication` event. For more information, see [Event message structure](notification-content-structure.md).
```
{
"Records": [
{
"eventVersion": "2.2",
"eventSource": "aws:s3",
"awsRegion": "us-east-1",
"eventTime": "2024-09-05T21:04:32.527Z",
"eventName": "Replication:OperationFailedReplication",
"userIdentity": {
"principalId": "s3.amazonaws.com"
},
"requestParameters": {
"sourceIPAddress": "s3.amazonaws.com"
},
"responseElements": {
"x-amz-request-id": "123bf045-2b4b-4ca8-a211-c34a63c59426",
"x-amz-id-2": "12VAWNDIHnwJsRhTccqQTeAPoXQmRt22KkewMV8G3XZihAuf9CLDdmkApgZzudaIe2KlLfDqGS0="
},
"s3": {
"s3SchemaVersion": "1.0",
"configurationId": "ReplicationEventName",
"bucket": {
"name": "amzn-s3-demo-bucket1",
"ownerIdentity": {
"principalId": "111122223333"
},
"arn": "arn:aws:s3:::amzn-s3-demo-bucket1"
},
"object": {
"key": "replication-object-put-test.png",
"size": 520080,
"eTag": "e12345ca7e88a38428305d3ff7fcb99f",
"versionId": "abcdeH0Xp66ep__QDjR76LK7Gc9X4wKO",
"sequencer": "0066DA1CBF104C0D51"
}
},
"replicationEventData": {
"replicationRuleId": "notification-test-replication-rule",
"destinationBucket": "arn:aws:s3:::amzn-s3-demo-bucket2",
"s3Operation": "OBJECT_PUT",
"requestTime": "2024-09-05T21:03:59.168Z",
"failureReason": "AssumeRoleNotPermitted"
}
}
]
}
```
## Amazon S3 replication failure reasons
The following table lists Amazon S3 Replication failure reasons. You can view these reasons by receiving the `s3:Replication:OperationFailedReplication` event with Amazon S3 Event Notifications and then looking at the `failureReason` value.
You can also view these failure reasons in an S3 Batch Replication completion report. For more information, see [Batch Replication completion report](s3-batch-replication-batch.md#batch-replication-completion-report).
| Replication failure reason | Description |
| --- | --- |
| `AssumeRoleNotPermitted` | Amazon S3 can't assume the AWS Identity and Access Management (IAM) role that's specified in the replication configuration or in the Batch Operations job. |
| `DstBucketInvalidRegion` | The destination bucket is not in the same AWS Region as specified by the Batch Operations job. This error is specific to Batch Replication. |
| `DstBucketNotFound` | Amazon S3 is unable to find the destination bucket that's specified in the replication configuration. |
| `DstBucketObjectLockConfigMissing` | To replicate objects from a source bucket with Object Lock enabled, the destination bucket must also have Object Lock enabled. This error indicates that Object Lock might not be enabled in the destination bucket. For more information, see [Object Lock considerations](object-lock-managing.md). |
| `DstBucketUnversioned` | Versioning is not enabled for the S3 destination bucket. To replicate objects with S3 Replication, enable versioning for the destination bucket. |
| `DstDelObjNotPermitted` | Amazon S3 is unable to replicate delete markers to the destination bucket. The `s3:ReplicateDelete` permission might be missing for the destination bucket. |
| `DstKmsKeyInvalidState` | The AWS Key Management Service (AWS KMS) key for the destination bucket isn't in a valid state. Review and enable the required AWS KMS key. For more information about managing AWS KMS keys, see [Key states of AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html) in the *AWS Key Management Service Developer Guide*. |
| `DstKmsKeyNotFound` | The AWS KMS key that's configured for the destination bucket in the replication configuration doesn't exist. |
| `DstMultipartCompleteNotPermitted` | Amazon S3 is unable to complete multipart uploads of objects in the destination bucket. The `s3:ReplicateObject` permission might be missing for the destination bucket. |
| `DstMultipartInitNotPermitted` | Amazon S3 is unable to initiate multipart uploads of objects to the destination bucket. The `s3:ReplicateObject` permission might be missing for the destination bucket. |
| `DstMultipartUploadNotPermitted` | Amazon S3 is unable to upload multipart upload objects to the destination bucket. The `s3:ReplicateObject` permission might be missing for the destination bucket. |
| `DstObjectHardDeleted` | S3 Batch Replication does not support re-replicating objects deleted with the version ID of the object from the destination bucket. This error is specific to Batch Replication. |
| `DstPutAclNotPermitted` | Amazon S3 is unable to replicate object access control lists (ACLs) to the destination bucket. The `s3:ReplicateObject` permission might be missing for the destination bucket. |
| `DstPutLegalHoldNotPermitted` | Amazon S3 is unable to put an Object Lock legal hold on the destination objects when it's replicating immutable objects. The `s3:PutObjectLegalHold` permission might be missing for the destination bucket. For more information, see [Legal holds](object-lock.md#object-lock-legal-holds). |
| `DstPutObjectNotPermitted` | Amazon S3 is unable to replicate objects to the destination bucket. This can occur when required permissions (`s3:ReplicateObject` or `s3:ObjectOwnerOverrideToBucketOwner` permissions) are missing for the destination bucket or when the AWS KMS key policy doesn't allow the source bucket's replication role to use the AWS KMS key (`kms:Decrypt` and `kms:GenerateDataKey*` actions) at the destination bucket. |
| `DstPutRetentionNotPermitted` | Amazon S3 is unable to put a retention period on the destination objects when it's replicating immutable objects. The `s3:PutObjectRetention` permission might be missing for the destination bucket. |
| `DstPutTaggingNotPermitted` | Amazon S3 is unable to replicate object tags to the destination bucket. The `s3:ReplicateObject` permission might be missing for the destination bucket. |
| `DstVersionNotFound ` | Amazon S3 is unable to find the required object version in the destination bucket for which metadata needs to be replicated. |
| `InitiateReplicationNotPermitted` | Amazon S3 is unable to initiate replication on objects. The `s3:InitiateReplication` permission might be missing for the Batch Operations job. This error is specific to Batch Replication. |
| `SrcBucketInvalidRegion` | The source bucket isn't in the same AWS Region as specified by the Batch Operations job. This error is specific to Batch Replication. |
| `SrcBucketNotFound` | Amazon S3 is unable to find the source bucket. |
| `SrcBucketReplicationConfigMissing` | Amazon S3 couldn't find a replication configuration for the source bucket. |
| `SrcGetAclNotPermitted` | Amazon S3 is unable to access the object in the source bucket for replication. The `s3:GetObjectVersionAcl` permission might be missing for the source bucket object. The objects in the source bucket must be owned by the bucket owner. If ACLs are enabled, then verify if Object Ownership is set to Bucket owner preferred or Object writer. If Object Ownership is set to Bucket owner preferred, then the source bucket objects must have the `bucket-owner-full-control` ACL for the bucket owner to become the object owner. The source account can take ownership of all objects in their bucket by setting Object Ownership to Bucket owner enforced and disabling ACLs. |
| `SrcGetLegalHoldNotPermitted` | Amazon S3 is unable to access the S3 Object Lock legal hold information. |
| `SrcGetObjectNotPermitted` | Amazon S3 is unable to access the object in the source bucket for replication. The `s3:GetObjectVersionForReplication` permission might be missing for the source bucket. |
| `SrcGetRetentionNotPermitted` | Amazon S3 is unable to access the S3 Object Lock retention period information. |
| `SrcGetTaggingNotPermitted` | Amazon S3 is unable to access object tag information from the source bucket. The `s3:GetObjectVersionTagging` permission might be missing for the source bucket. |
| `SrcHeadObjectNotPermitted` | Amazon S3 is unable to retrieve object metadata from the source bucket. The `s3:GetObjectVersionForReplication` permission might be missing for the source bucket. |
| `SrcKeyNotFound` | Amazon S3 is unable to find the source object key to replicate. Source object may have been deleted before replication was complete. |
| `SrcKmsKeyInvalidState` | The AWS KMS key for the source bucket isn't in a valid state. Review and enable the required AWS KMS key. For more information about managing AWS KMS keys, see [Key states of AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html) in the *AWS Key Management Service Developer Guide*. |
| `SrcObjectNotEligible` | Some objects aren't eligible for replication. This may be due to the object's storage class or the object tags don't match the replication configuration. |
| `SrcObjectNotFound` | Source object does not exist. |
| `SrcReplicationNotPending` | Amazon S3 has already replicated this object. This object is no longer pending replication. |
| `SrcVersionNotFound` | Amazon S3 is unable to find the source object version to replicate. Source object version may have been deleted before replication was complete. |
### Related topics
[Setting up permissions for live replication](setting-repl-config-perm-overview.md)
[Troubleshooting replication](replication-troubleshoot.md)
# Getting replication status information
Replication status can help you determine the current state of an object being replicated. The replication status of a source object will return either `PENDING`, `COMPLETED`, or `FAILED`. The replication status of a replica will return `REPLICA`.
You can also use replication status values when you're creating S3 Batch Replication jobs. For example, you can use these status values to replicate objects that have either never been replicated or that have failed replication. For more information about using these values with Batch Replication, see [Using replication status information with Batch Replication jobs](#replication-status-batch-replication).
**Topics**
+ [
## Replication status overview
](#replication-status-overview)
+ [
## Replication status if replicating to multiple destination buckets
](#replication-status-multiple-destinations)
+ [
## Replication status if Amazon S3 replica modification sync is enabled
](#replication-status-replica-mod-syn)
+ [
## Using replication status information with Batch Replication jobs
](#replication-status-batch-replication)
+ [
## Finding replication status
](#replication-status-usage)
## Replication status overview
In replication, you have a source bucket on which you configure replication and one or more destination buckets where Amazon S3 replicates objects. When you request an object (by using `GetObject`) or object metadata (by using `HeadObject`) from these buckets, Amazon S3 returns the `x-amz-replication-status` header in the response:
+ When you request an object from the source bucket, Amazon S3 returns the `x-amz-replication-status` header if the object in your request is eligible for replication.
For example, suppose that you specify the object prefix `TaxDocs` in your replication configuration to tell Amazon S3 to replicate only objects with the key name prefix `TaxDocs`. Any objects that you upload that have this key name prefix—for example, `TaxDocs/document1.pdf`—will be replicated. For object requests with this key name prefix, Amazon S3 returns the `x-amz-replication-status` header with one of the following values for the object's replication status: `PENDING`, `COMPLETED`, or `FAILED`.
**Note**
If object replication fails after you upload an object, you can't retry replication. You must upload the object again, or you must use S3 Batch Replication to replicate any failed objects. S3 Lifecycle blocks expiration and transition actions on objects with `PENDING` or `FAILED` replication status. For more information about using Batch Replication, see [Replicating existing objects with Batch Replication](s3-batch-replication-batch.md).
Objects transition to a `FAILED` state for issues such as missing replication role permissions, AWS Key Management Service (AWS KMS) permissions, or bucket permissions. For temporary failures, such as if a bucket or Region is unavailable, replication status doesn't transition to `FAILED`, but remains `PENDING`. After the resource is back online, Amazon S3 resumes replicating those objects.
+ When you request an object from a destination bucket, if the object in your request is a replica that Amazon S3 created, Amazon S3 returns the `x-amz-replication-status` header with the value `REPLICA`.
**Note**
Before deleting an object from a source bucket that has replication enabled, check the object's replication status to make sure that the object has been replicated.
If an S3 Lifecycle configuration is enabled on the source bucket, Amazon S3 suspends lifecycle actions until it marks the object's replication status as `COMPLETED`. If replication status is `FAILED`, S3 Lifecycle continues to block expiration and transition actions on the object until you resolve the underlying replication issue. For more information, see [S3 Lifecycle and](lifecycle-and-other-bucket-config.md#lifecycle-and-replication).
## Replication status if replicating to multiple destination buckets
When you replicate objects to multiple destination buckets, the `x-amz-replication-status` header acts differently. The header of the source object returns a value of `COMPLETED` only when replication is successful to all destinations. The header remains at the `PENDING` value until replication has completed for all destinations. If one or more destinations fail replication, the header returns `FAILED`.
## Replication status if Amazon S3 replica modification sync is enabled
When your replication rules enable Amazon S3 replica modification sync, replicas can report statuses other than `REPLICA`. If metadata changes are in the process of replicating, the `x-amz-replication-status` header returns `PENDING`. If replica modification sync fails to replicate metadata, the header returns `FAILED`. If metadata is replicated correctly, the replicas return the header `REPLICA`.
## Using replication status information with Batch Replication jobs
When creating a Batch Replication job, you can optionally specify additional filters, such as the object creation date and replication status, to reduce the scope of the job.
You can filter objects to replicate based on the `ObjectReplicationStatuses` value, by providing one or more of the following values:
+ `"NONE"` – Indicates that Amazon S3 has never attempted to replicate the object before.
+ `"FAILED"` – Indicates that Amazon S3 has attempted, but failed, to replicate the object before.
+ `"COMPLETED"` – Indicates that Amazon S3 has successfully replicated the object before.
+ `"REPLICA"` – Indicates that this is a replica object that Amazon S3 has replicated from another source.
For more information about using these replication status values with Batch Replication, see [Filters for a Batch Replication job](s3-batch-replication-batch.md#batch-replication-filters).
## Finding replication status
To get the replication status of the objects in a bucket, you can use the Amazon S3 Inventory tool. Amazon S3 sends a CSV file to the destination bucket that you specify in the inventory configuration. You can also use Amazon Athena to query the replication status in the inventory report. For more information about Amazon S3 Inventory, see [Cataloging and analyzing your data with S3 Inventory](storage-inventory.md).
You can also find the object replication status by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), or the AWS SDK.
### Using the S3 console
In the Amazon S3 console, you can view the replication status for an object on the object's details page.
1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. In the left navigation pane, choose **Buckets**.
1. In the **General purpose buckets** list, choose the name of the replication source bucket.
1. In the **Objects** list, choose the object name. The object's details page appears.
1. On the **Properties** tab, scroll down to the **Object management overview** section. Under **Management configurations**, see the value under **Replication status**.
### Using the AWS CLI
Use the AWS Command Line Interface (AWS CLI) `head-object` command to retrieve object metadata, as shown in the following example. Replace the `amzn-s3-demo-source-bucket1` with the name of your replication source bucket, and replace the other `user input placeholders` with your own information.
```
aws s3api head-object --bucket amzn-s3-demo-source-bucket1 --key object-key --version-id object-version-id
```
The command returns object metadata, including the `ReplicationStatus` as shown in the following example response.
```
{
"AcceptRanges":"bytes",
"ContentType":"image/jpeg",
"LastModified":"Mon, 23 Mar 2015 21:02:29 GMT",
"ContentLength":3191,
"ReplicationStatus":"COMPLETED",
"VersionId":"jfnW.HIMOfYiD_9rGbSkmroXsFj3fqZ.",
"ETag":"\"6805f2cfc46c0f04559748bb039d69ae\"",
"Metadata":{
}
}
```
### Using the AWS SDKs
The following code fragments get your replication status by using the AWS SDK for Java and AWS SDK for .NET, respectively.
------
#### [ Java ]
```
GetObjectMetadataRequest metadataRequest = new GetObjectMetadataRequest(bucketName, key);
ObjectMetadata metadata = s3Client.getObjectMetadata(metadataRequest);
System.out.println("Replication Status : " + metadata.getRawMetadataValue(Headers.OBJECT_REPLICATION_STATUS));
```
------
#### [ .NET ]
```
GetObjectMetadataRequest getmetadataRequest = new GetObjectMetadataRequest
{
BucketName = sourceBucket,
Key = objectKey
};
GetObjectMetadataResponse getmetadataResponse = client.GetObjectMetadata(getmetadataRequest);
Console.WriteLine("Object replication status: {0}", getmetadataResponse.ReplicationStatus);
```
------