Creating a metrics configuration that filters by object key name prefix or tag - Amazon Simple Storage Service

Creating a metrics configuration that filters by object key name prefix or tag

There are three types of Amazon CloudWatch metrics for Amazon S3: storage metrics, request metrics, and replication metrics. Storage metrics are reported once per day and are provided to all customers at no additional cost. Request metrics are available at one-minute intervals after some latency to process. Request metrics are billed at the standard CloudWatch rate. You must opt into request metrics by configuring them in the console or using the Amazon S3 API.

For more information about CloudWatch metrics for Amazon S3, see Monitoring metrics with Amazon CloudWatch.

When you configure CloudWatch metrics, you can create a filter for all the objects in your bucket or you can filter 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 – Although 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 are included in the metrics configuration.

  • Tag – You can add tags, which are key-value name pairs, to objects. Tags help you find and organize objects easily. You can also use tags as filters for metrics configurations.

If you specify a filter, only requests that operate on single objects can match the filter and be included in the reported metrics. Requests like Delete Multiple Objects and List requests don't return any metrics for configurations with filters.

To request more complex filtering, choose two or more elements. Only objects that have all of those elements are included in the metrics configuration. If you don't set filters, all of the objects in the bucket are included in the metrics configuration.

  1. Sign in to the AWS Management Console and open the Amazon S3 console at

  2. In the Buckets list, choose the name of the bucket that contains the objects you want request metrics for.

  3. Choose the Metrics tab.

  4. Under Bucket metrics, choose View additional charts.

  5. Choose the Request metrics tab.

  6. Choose Create filter.

  7. In the Filter name box, enter your filter name.

    Names can only contain letters, numbers, periods, dashes, and underscores.

  8. Under Choose a filter scope, choose Limit the scope of this filter using prefix and tags.

  9. (Optional) In the Prefix box, enter a prefix to limit the scope of the filter to a single path.

  10. (Optional) Under Tags, enter a tag Key and Value.

  11. Choose Create filter.

    Amazon S3 creates a filter that uses the tags or prefixes you specified.

  12. On the Request metrics tab, under Filters, choose the filter that you just created.

    You have now created a filter that limits the request metrics scope by object tags and prefixes. About 15 minutes after CloudWatch begins tracking these request metrics, you can see charts for the metrics on both the Amazon S3 and CloudWatch consoles. Request metrics are billed at the standard CloudWatch rate. For more information, see Amazon CloudWatch pricing.

    You can also configure request metrics at the bucket level. For information, see Creating a CloudWatch metrics configuration for all the objects in your bucket.

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

  1. Install and set up the AWS CLI. For instructions, see Installing, updating, and uninstalling the AWS CLI 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"}}" '