Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)

Metrics Configurations for Buckets

The CloudWatch request metrics for Amazon S3 enable you to receive 1-minute CloudWatch metrics, set CloudWatch alarms, and access CloudWatch dashboards to view near real-time operations and performance of your Amazon S3 storage. For applications that depend on Cloud storage, these metrics let you quickly identify and act on operational issues. When enabled, these 1-minute metrics are available at the Amazon S3 bucket-level, by default.

You must create a metrics configuration for a bucket if you want to get the CloudWatch request metrics for the objects in that bucket. You can also define a filter for the metrics collected –using a shared prefix or object tags– allowing you to align metrics filters to specific business applications, workflows, or internal organizations.

Keep the following in mind when using metrics configurations:

  • You can have up to 1000 metrics configuration per bucket.

  • Metrics configurations are only necessary for bucket-level and object-level request metrics. The bucket-level daily storage metrics are always turned on and are provided at no additional cost.

  • Using filters, you can choose which objects in a bucket are part of which metrics configurations. These filters can use a shared prefix or object tag, allowing you to align metrics filters to specific business applications, workflows, or internal organizations.

  • Each metrics configuration reports all available request metrics.

  • Metrics configurations are also reported for operations that list bucket contents, like Get Bucket (List Objects), GET Bucket Object versions, and List Multipart Uploads, but are not reported for the other operations on buckets that access or modify bucket subresources.

Best Effort CloudWatch Metrics Delivery

CloudWatch metrics are delivered on a best effort basis. Most requests for an Amazon S3 object that have request metrics will result in a data point being sent to CloudWatch.

The completeness and timeliness of metrics is not guaranteed. The data point for a particular request might be returned with a timestamp that is later than when the request was actually processed, or the data point for a minute might be delayed before being available through CloudWatch, or it might not be delivered at all. CloudWatch request metrics give you an idea of the nature of traffic against your bucket in near real time. It is not meant to be a complete accounting of all requests.

It follows from the best-effort nature of this feature that the reports available at the Billing & Cost Management Dashboard might include one or more access requests that do not appear in the bucket metrics.

Filtering Metrics Configurations

When working with CloudWatch metric configurations, you have the option of filtering the configuration into groups of related objects within a single bucket. You can filter objects in a bucket for inclusion in a metrics configuration based on one or more of the following elements:

  • Object key name prefix – While the Amazon S3 data model is a flat structure, you can infer hierarchy by using a prefix. The Amazon S3 console supports these prefixes with the concept of folders. If you filter by prefix, objects that have the same prefix will be included in the metrics configuration.

  • Tag – You can add tags, key value name pairs, to objects. Tags allow you to find and organize objects easily. These tags can also be used as a filter for metrics configurations.

More complex filtering is done by choosing two or more elements, and only objects that have all those elements are included in the metrics configuration.

If no filters are selected, then all the objects in the bucket are part of the metrics configuration.

How to Add Metrics Configurations

You can add metrics configurations to a bucket through the Amazon S3 console, with the AWS CLI, or with the Amazon S3 REST API. For information about how to do this in the AWS Management Console, see the Amazon S3 Console User Guide.

Add Metrics Configurations with the AWS CLI

  1. Install and set up the AWS CLI. For instructions, see Getting Set Up with the AWS Command Line Interface in the AWS Command Line Interface User Guide.

  2. Open a terminal.

  3. Run the following command to add a metrics configuration:

    aws s3api put-bucket-metrics-configuration --endpoint --bucket bucket-name --id metrics-config-id --metrics-configuration '{"Id":" metrics-config-id ","Filter":{"Prefix":"prefix1"}}'
  4. To verify that the configuration was added, execute the following command:

    aws s3api get-bucket-metrics-configuration --endpoint --bucket bucket-name --id metrics-config-id

    This returns the following response:

    { "MetricsConfiguration": { "Filter": { "Prefix": "prefix1" }, "Id": "metrics-config-id" } }

You can also add metrics configurations programmatically with the Amazon S3 REST API. For more information, see the following topics in the Amazon Simple Storage Service API Reference: