# Analyzing data access using CloudWatch contributor insights for DynamoDB Contributor Insights Amazon CloudWatch Contributor Insights for Amazon DynamoDB is a diagnostic tool for identifying the most frequently accessed and throttled keys in your table or index at a glance. This tool uses [CloudWatch contributor insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html). By enabling CloudWatch Contributor Insights for DynamoDB on a table or global secondary index, you can view the most accessed and throttled items in those resources. **Note** CloudWatch charges apply for Contributor Insights for DynamoDB. For more information about pricing, see [ Amazon CloudWatch pricing](https://aws.amazon.com/cloudwatch/pricing/). **Topics** + [How it works](contributorinsights_HowItWorks.md) + [Getting started](contributorinsights_tutorial.md) + [Using IAM](Contributor_Insights_IAM.md) # CloudWatch contributor insights for DynamoDB: How it works How it works Amazon DynamoDB integrates with [CloudWatch Contributor Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html) to provide information about the most accessed and throttled items in a table or global secondary index. DynamoDB delivers this information to you via CloudWatch Contributor Insights [rules](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights-RuleSyntax.html), [reports](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights-ViewReports.html), and [graphs of report data](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights-GraphReportData.html). CloudWatch Contributor Insights for DynamoDB is designed to have no performance impact on your DynamoDB table. For more information about CloudWatch Contributor Insights, see [Using Contributor Insights to analyze high-cardinality data](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html) in the *Amazon CloudWatch User Guide*. The following sections describe the core concepts and behavior of CloudWatch Contributor Insights for DynamoDB. **Topics** + [ ## CloudWatch contributor insights modes for DynamoDB ](#contributorinsights_HowItWorks.Modes) + [ ## CloudWatch contributor insights for DynamoDB rules ](#contributorinsights_HowItWorks.Rules) + [ ## Understanding CloudWatch contributor insights for DynamoDB graphs ](#contributorinsights_HowItWorks.Graphs) + [ ## Interactions with other DynamoDB features ](#contributorinsights_HowItWorks.OtherFeatures) + [ ## CloudWatch contributor insights for DynamoDB billing ](#contributorinsights_HowItWorks.Billing) ## CloudWatch contributor insights modes for DynamoDB CloudWatch Contributor Insights for DynamoDB offers two distinct modes to meet different monitoring needs. ### Throttled keys mode This mode focuses exclusively on throttled requests by only processing events when throttling occurs. It delivers insights about performance issues without the overhead of tracking all access patterns. In this mode, DynamoDB tracks only the: + **Most throttled items** — Items that experience the most throttling events This mode is ideal when: + Your primary concern is identifying and resolving throttling problems + You want to keep Contributor Insights enabled continuously for real-time throttling detection + You want a cost-optimized approach to monitor throttling issues **Note** *Throttled keys mode* processes events only when throttling occurs, making it cost-effective for continuous monitoring. This targeted approach allows you to leave the feature enabled permanently with minimal cost impact, while still providing immediate visibility into throttling issues as they happen. If your table experiences no throttling, you won't see any data in the Contributor Insights graphs, which indicates healthy performance. When throttling is detected, the generated graphs help you identify specific access patterns causing performance issues. This information can help you implement strategies to address non-uniform access patterns. For comprehensive monitoring strategies, you can integrate these throttling insights with other CloudWatch metrics to create unified dashboards that correlate throttling events with overall table performance. ### Accessed and throttled keys mode This mode provides comprehensive monitoring of both accessed and throttled items. In this mode, DynamoDB tracks the: + **Most accessed items** — Items that consume the most read and write capacity + **Most throttled items** — Items that experience the most throttling events This mode is ideal when you need complete visibility into your table's access patterns and want to understand both high-traffic items and throttling issues. ### Switching between modes You can switch between modes at any time using the DynamoDB console, AWS CLI, or APIs. When you switch modes: + Existing CloudWatch rules are updated to match the new mode + Throttled keys CloudWatch rules remain intact, maintaining your continuous historical data for throttling metrics: + When you switch from *throttled keys* mode to *accessed and throttled keys* mode, the existing throttled key rules are preserved, and new accessed key rules are created + When you switch from *accessed and throttled keys* mode to *throttled keys* mode, only the throttled key rules are preserved, and the accessed key rules are removed + Billing adjusts immediately to reflect the new mode's event processing ## CloudWatch contributor insights for DynamoDB rules When you enable CloudWatch Contributor Insights for DynamoDB on a table or global secondary index, DynamoDB creates [rules](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights-RuleSyntax.html) on your behalf based on the selected mode. **Note** When you enable Contributor Insights on your DynamoDB table, you're subject to Contributor Insights rules limits. For more information, see [CloudWatch service quotas](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_limits.html). ### Rules for accessed and throttled keys mode In *accessed and throttled keys* mode, DynamoDB creates the following rules: + **Most accessed items (partition keys)** — Identifies the partition keys of the most accessed items in your table or global secondary index. CloudWatch rule name format: `DynamoDBContributorInsights-PKC-[resource_name]-[creationtimestamp]` + **Most throttled keys (partition keys)** — Identifies the partition keys of the most throttled items in your table or global secondary index. CloudWatch rule name format: `DynamoDBContributorInsights-PKT-[resource_name]-[creationtimestamp]` If your table or global secondary index has sort keys, DynamoDB also creates the following rules specific to sort keys: + **Most accessed keys (partition and sort keys)** — Identifies the partition and sort keys of the most accessed items in your table or global secondary index. CloudWatch rule name format: `DynamoDBContributorInsights-SKC-[resource_name]-[creationtimestamp]` + **Most throttled keys (partition and sort keys)** — Identifies the partition and sort keys of the most throttled items in your table or global secondary index. CloudWatch rule name format: `DynamoDBContributorInsights-SKT-[resource_name]-[creationtimestamp]` ### Rules for throttled keys mode In *throttled keys* mode, DynamoDB creates only the throttling-related rules: + **Most throttled keys (partition key)** — Identifies the partition keys of the most throttled items in your table or global secondary index. CloudWatch rule name format: `DynamoDBContributorInsights-PKT-[resource_name]-[creationtimestamp]` If your table or global secondary index has sort keys, DynamoDB also creates: + **Most throttled keys (partition and sort keys)** — Identifies the partition and sort keys of the most throttled items in your table or global secondary index. CloudWatch rule name format: `DynamoDBContributorInsights-SKT-[resource_name]-[creationtimestamp]` This focused approach reduces the number of active rules and decreases the volume of events processed to better diagnose your throttling events. **Note** When you use the CloudWatch console or APIs to view CloudWatch Contributor Insights for DynamoDB, you only see rules corresponding to your selected mode. You can't use the CloudWatch console or APIs to directly modify or delete the rules created by CloudWatch Contributor Insights for DynamoDB. Disabling CloudWatch Contributor Insights for DynamoDB on a table or global secondary index automatically deletes the rules created for that table or global secondary index. When you use the [GetInsightRuleReport](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetInsightRuleReport.html) operation with CloudWatch Contributor Insights rules that are created by DynamoDB, only `MaxContributorValue` and `Maximum` return useful statistics. The other statistics in this list don't return meaningful values. CloudWatch Contributor Insights for DynamoDB has a limit of 25 contributors. Requesting more than 25 contributors will return an error. You can create CloudWatch Alarms using the CloudWatch Contributor Insights for DynamoDB [rules](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights-RuleSyntax.html). This allows you to be notified when any item exceed or meets a specific threshold for `ConsumedThroughputUnits` or `ThrottleCount`. For more information, see [Setting an alarm on Contributor Insights metric data](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights-GraphReportData.html#ContributorInsights-GraphReportData-Alarm). ## Understanding CloudWatch contributor insights for DynamoDB graphs CloudWatch Contributor Insights for DynamoDB displays different types of graphs on both the DynamoDB and CloudWatch consoles depending on the selected mode. ### Graph availability by mode The graphs displayed depend on your selected Contributor Insights mode. + **Accessed and throttled keys mode** displays both *Most Accessed Items* and *Most Throttled Items* graphs + **Throttled keys mode** displays only *Most Throttled Items* graphs ### Most accessed items This graph is available only in accessed and throttled keys mode. Use this graph to identify the most accessed items in the table or global secondary index. The graph displays `ConsumedThroughputUnits` on the y-axis and time on the x-axis. Each of the top N keys is displayed in its own color, with a legend displayed below the x-axis. DynamoDB measures key access frequency by using `ConsumedThroughputUnits`, which measures combined read and write traffic. `ConsumedThroughputUnits` is defined as the following: + Provisioned — *(3 x consumed write capacity units) \$1 consumed read capacity units* + On-demand — *(3 x write request units) \$1 read request units* On the DynamoDB console, each data point in the graph represents the maximum of `ConsumedThroughputUnits` over a 1-minute period. For example, a graph value of 180,000 `ConsumedThroughputUnits` indicates that the item was accessed continuously at the per-item maximum throughput of 1,000 write request units or 3,000 read request units for a 60-second span within that 1-minute period (3,000 x 60 seconds). In other words, the graphed values represent the highest-traffic minute within each 1-minute period. You can change the time granularity of the `ConsumedThroughputUnits` metric (for example, to view 5-minute metrics instead of 1-minute) on the CloudWatch console. If you see several closely clustered lines without any obvious outliers, it indicates that your workload is relatively balanced across items over the given time window. If you see isolated points in the graph instead of connected lines, it indicates an item that was frequently accessed only for a brief period. If your table or global secondary index has sort keys, DynamoDB creates two graphs: one for the most accessed partition keys and one for the most accessed partition \$1 sort keys pairs. You can see traffic at the partition keys level in the partition key–only graph. You can see traffic at the item level in the partition \$1 sort keys graphs. ### Most throttled items This graph is available in both modes. Use this graph to identify the most throttled items in the table or global secondary index. The graph displays `ThrottleCount` on the y-axis and time on the x-axis. Each of the top *N* keys is displayed in its own color, with a legend displayed below the x-axis. DynamoDB measures throttle frequency using `ThrottleCount`, which is the count of `ProvisionedThroughputExceededException`, `ThrottlingException`, and `RequestLimitExceeded` errors. Write throttling caused by insufficient write capacity for a global secondary index is not measured. You can use the *Most Accessed Items* graph of the global secondary index to identify imbalanced access patterns that may cause write throttling. For more information, see [Provisioned throughput Considerations for Global Secondary Indexes](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html#GSI.ThroughputConsiderations). On the DynamoDB console, each data point in the graph represents the count of throttle events over a 1-minute period. If you see no data in this graph, it indicates that your requests are not being throttled. If you see isolated points in the graph instead of connected lines, it indicates that an item was frequently throttled for a brief period. If your table or global secondary index has sort keys, DynamoDB creates two graphs: one for most throttled partition keys and one for most throttled partition \$1 sort keys pairs. You can see throttle count at the partition keys level in the partition keys-only graph, and throttle count at the item-level in the partition \$1 sort keys graphs. **Note** In *throttled keys* mode, this is the only type of graph you'll see. The absence of data in these graphs indicates healthy table performance with no throttling occurring. ### Report examples The following example shows the reports generated for a table with both a partition keys and sort keys in *accessed and throttled keys* modes. In *throttled keys* mode, you see only the throttling-related portion of this report. ![\[4 different Contributor Insights reports showing most accessed items and most throttled items.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/CI_Graphs_Example.png) ## Interactions with other DynamoDB features The following sections describe how CloudWatch Contributor Insights for DynamoDB behaves and interacts with several other features in DynamoDB. These behaviors apply to both modes unless otherwise specified. ### Global tables CloudWatch Contributor Insights for DynamoDB monitors global table replicas as distinct tables. The Contributor Insights graphs for a replica in one AWS Region might not show the same patterns as another Region. This is because write data is replicated across all replicas in a global table, but each replica can serve Region-bound read traffic. Each replica can be configured with a different Contributor Insights mode independently. For example, you might use *accessed and throttled keys* mode in your primary region for comprehensive monitoring, while using *throttled keys* mode in secondary regions to maintain visibility into performance issues. ### DynamoDB Accelerator (DAX) CloudWatch Contributor Insights for DynamoDB doesn't show DAX cache responses. It only shows responses to accessing a table or a global secondary index. **Note** DynamoDB CloudWatch Contributor Insights does not support PartiQL requests. ### Encryption at rest CloudWatch Contributor Insights for DynamoDB doesn't affect how encryption works in DynamoDB. The primary key data that is published in CloudWatch is encrypted with the AWS owned key. However, DynamoDB also supports the AWS managed key and a customer managed key. CloudWatch Contributor Insights for DynamoDB displays partition keys and sort keys (if applicable) of frequently accessed and throttled items. While CloudWatch Contributor Insights works with encrypted DynamoDB tables, it's important to note that it uses its own Amazon-owned encryption context, which is separate from the table's configured encryption. If your DynamoDB table's primary key contains sensitive information and your organization's security policies require full control over encryption processes, enabling CloudWatch Contributor Insights may not be suitable. ### Fine-grained access control CloudWatch Contributor Insights for DynamoDB doesn't function differently for tables with fine-grained access control (FGAC). In other words, any user who has the appropriate CloudWatch permissions can view FGAC-protected primary keys in CloudWatch Contributor Insights graphs. If the table's primary key contains FGAC-protected data that you don't want published to CloudWatch, you should not enable CloudWatch Contributor Insights for DynamoDB for that table. ### Access control You control access to CloudWatch Contributor Insights for DynamoDB using AWS Identity and Access Management (IAM) by limiting DynamoDB control plane permissions and CloudWatch data plane permissions. For more information see, [Using IAM with CloudWatch Contributor Insights for DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Contributor_Insights_IAM.html). ## CloudWatch contributor insights for DynamoDB billing Charges for CloudWatch Contributor Insights for DynamoDB appear in the [CloudWatch](https://aws.amazon.com/cloudwatch/pricing/) section of your monthly bill. These charges are calculated based on the number of DynamoDB events that are processed, and the selected mode. ### Billing by mode The two Contributor Insights modes have different billing characteristics. + **Accessed and throttled keys mode billing** - In this mode, each item that is written or read via a [data plane](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.API.html#HowItWorks.API.DataPlane) operation represents one event, regardless of whether the request succeeds or is throttled. If a table or global secondary index includes sort keys, each item that is read or written represents two events. This is because DynamoDB is identifying top contributors from separate time series: one for partitions keys only, and one for partition and sort keys pairs. + **Throttled keys mode billing** - In this mode, only throttled requests generate billable events. Events are only generated when requests result in `ProvisionedThroughputExceededException`, `ThrottlingException`, or `RequestLimitExceeded` errors. If a table or global secondary index includes sort keys, each throttled item represents two events (partition keys tracking and partition \$1 sort keys tracking). ### Billing examples For example, assume that your application performs the following DynamoDB operations: a `GetItem`, a `PutItem`, and a `BatchWriteItem` that puts five items. Also assume that the `PutItem` operation gets throttled, but all other operations succeed. + **Accessed and throttled keys mode** + If your table or global secondary index has only a partition keys, it results in 7 events (1 for the `GetItem`, 1 for the `PutItem`, and 5 for the `BatchWriteItem`). + If your table or global secondary index has a partition keys and sort keys, it results in 14 events (2 for the `GetItem`, 2 for the `PutItem`, and 10 for the `BatchWriteItem`). + **Throttled keys mode** + If your table or global secondary index has only a partition keys, it results in 1 event (only for the throttled `PutItem`). + If your table or global secondary index has a partition keys and sort keys, it results in 2 events (2 for the throttled `PutItem`). The successful `GetItem` and `BatchWriteItem` operations generate no events in throttled keys mode. ### Common billing factors A`Query` operation always results in 1 event, regardless of the mode or number of items returned. Unlike other DynamoDB features, CloudWatch Contributor Insights for DynamoDB billing *does not* vary based on the following: + The [capacity mode](capacity-mode.md) (provisioned vs. on-demand) + Whether you perform read or write requests + The size (KB) of the items read or written # Getting started with CloudWatch Contributor Insights for DynamoDB Getting started This section describes how to enable and use Amazon CloudWatch Contributor Insights in different modes to meet your monitoring needs using the Amazon DynamoDB console or the AWS Command Line Interface (AWS CLI). In the following examples, you use the DynamoDB table that is defined in the [Getting started with DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) tutorial. **Topics** + [ ## Choosing a Contributor Insights mode ](#contributorinsights_tutorial.modes) + [ ## Using Contributor Insights (console) ](#usecontributorinsights_console) + [ ## Using Contributor Insights (AWS CLI) ](#usecontributorinsights_cli) ## Choosing a Contributor Insights mode Before enabling Contributor Insights, you should understand the two available modes. Review the mode comparison to select the option that best aligns with your specific requirements. | Aspect | Accessed and throttled keys mode | Throttled keys mode | | --- | --- | --- | | Monitors | All requests (successful and throttled) | Only throttled requests | | Graphs | Most Accessed Items \$1 Most Throttled Items | Most Throttled Items only | | Best for | Targeted analysis and optimization | Throttling monitoring | | Use when | You need complete visibility into access patterns. You're doing short-term analysis or debugging. | Your primary concern is identifying and resolving throttling issues. You want to keep Contributor Insights enabled continuously for real-time throttling alerts. | ## Using Contributor Insights (console) The console provides an intuitive way to enable Contributor Insights and select the appropriate mode for your monitoring needs. **To use Contributor Insights in the console** 1. Sign in to the AWS Management Console and open the DynamoDB console at [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/). 1. In the navigation pane on the left side of the console, choose **Tables**. 1. Choose the `Music` table. 1. Choose the **Monitor** tab. 1. Choose **Turn on CloudWatch Contributor Insights**. ![\[Console screenshot showing monitor tab and button.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/CI_ChooseAndManageNew.PNG) 1. In the **Manage CloudWatch Contributor Insights settings** dialog box, toggle **Turn on** for both the `Music` base table and the `AlbumTitle-index` global secondary index. 1. Leave the **Only throttled keys mode** toggle in the off position for both and then choose **Save changes**. ![\[Console screenshot showing Contributor Insights status list options.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/CI_Enable.png) This enables the default *accessed and throttled keys* mode for both the table and GSI, which provides monitoring of both accessed and throttled items. Switching the **Only throttled keys mode** toggle to the on position would enable the *throttled keys* mode. If the operation fails, see [DescribeContributorInsights FailureException](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeContributorInsights.html#DDB-DescribeContributorInsights-response-FailureException) in the *Amazon DynamoDB API Reference* for possible reasons. 1. The CloudWatch Contributor Insights graphs are now visible on the **Monitor** tab for the `Music` table. Since you enabled *accessed and throttled keys* mode, you see both accessed and throttled item graphs. ![\[Console screenshot showing Contributor Insights tab with several graphs for the music table.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/CI_Graphs.png) ### Switching between modes You can switch between modes at any time without disabling Contributor Insights. **To switch Contributor Insights modes** 1. On the **Monitor** tab of your table, choose **Manage CloudWatch Contributor Insights**. 1. In the **Manage Contributor Insights settings** dialog box, for each base table or GSIs: + Toggle **Only throttled keys mode** on or off to enable the *throttled keys* mode or go back to the default *accessed and throttled keys* mode. + Toggle **Turn on** off to disable CloudWatch Contributor Insight for a table or GSI. 1. Choose **Save changes**. Once complete, the graphs will reflect the new mode. ### Creating CloudWatch alarms Follow these steps to create a CloudWatch alarm and be notified when any partition key consumes more than 50,000 [ConsumedThroughputUnits](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/contributorinsights_HowItWorks.html#contributorinsights_HowItWorks.Graphs.most-accessed) or experiences throttling. 1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 1. In the navigation pane on the left side of the console, choose **Contributor Insights**. 1. Choose the appropriate rule based on your mode and what you want to monitor: + For accessed items monitoring (accessed and throttled keys mode only): Choose **DynamoDBContributorInsights-PKC-Music** + For throttled items monitoring (both modes): Choose **DynamoDBContributorInsights-PKT-Music** 1. Choose the **Actions** drop down. 1. Choose **View in metrics**. 1. Choose **Max Contributor Value**. **Note** Only `Max Contributor Value` and `Maximum` return useful statistics. The other statistics in this list don't return meaningful values. ![\[Console screenshot showing Contributor Insights tab and button.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/CI_AlarmsViewinMetrics.png) 1. On the **Actions** column, Choose **Create Alarm**. ![\[Console screenshot showing Contributor Insights status list options.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/CI_AlarmsSetAlarm.png) 1. Enter an appropriate threshold value and choose **Next**: + For accessed items (PKC rules): Enter 50000 for `ConsumedThroughputUnits` + For throttled items (PKT rules): Enter 1 for `ThrottleCount` to be alerted on any throttling ![\[Console screenshot showing Contributor Insights tab and button.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/CI_AlarmsSetAlarmThreashold.png) 1. See [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) for details on how to configure the notification for the alarm. ## Using Contributor Insights (AWS CLI) The AWS CLI provides programmatic access to Contributor Insights with full support for both modes. You can specify the mode when enabling Contributor Insights or switch modes later. ### Basic operations with default mode **To use Contributor Insights with default settings** 1. Enable CloudWatch Contributor Insights for DynamoDB on the `Music` base table with the *accessed and throttled keys* mode. Since `ACCESSED_AND_THROTTLED_KEYS` is the default mode, you can omit the `--contributor-insights-mode=ACCESSED_AND_THROTTLED_KEYS` parameter. ``` aws dynamodb update-contributor-insights \ --table-name Music \ --contributor-insights-action=ENABLE ``` 1. Enable Contributor Insights for DynamoDB on the `AlbumTitle-index` global secondary index. ``` aws dynamodb update-contributor-insights \ --table-name Music \ --index-name AlbumTitle-index \ --contributor-insights-action=ENABLE ``` 1. Get the status and rules for the `Music` table and all its indexes. ``` aws dynamodb describe-contributor-insights --table-name Music ``` The response will include the `ContributorInsightsMode` field showing `ACCESSED_AND_THROTTLED_KEYS`. 1. List the status of the `Music` table and all its indexes. ``` aws dynamodb list-contributor-insights --table-name Music ``` ### Enabling throttled keys mode **To enable Contributor Insights in throttled keys mode** 1. Enable CloudWatch Contributor Insights for DynamoDB on the `Music` base table with *throttled keys* mode. ``` aws dynamodb update-contributor-insights \ --table-name Music \ --contributor-insights-action=ENABLE \ --contributor-insights-mode=THROTTLED_KEYS ``` 1. Enable Contributor Insights in *throttled keys* mode for the `AlbumTitle-index` global secondary index. ``` aws dynamodb update-contributor-insights \ --table-name Music \ --index-name AlbumTitle-index \ --contributor-insights-action=ENABLE \ --contributor-insights-mode=THROTTLED_KEYS ``` 1. Verify the mode by describing the Contributor Insights configuration. ``` aws dynamodb describe-contributor-insights --table-name Music ``` The response will show `ContributorInsightsMode` as `THROTTLED_KEYS` and fewer rules compared to the default mode. ### Switching between modes **To switch Contributor Insights modes** 1. Switch from *throttled keys* mode to *accessed and throttled keys* mode. ``` aws dynamodb update-contributor-insights \ --table-name Music \ --contributor-insights-action=ENABLE \ --contributor-insights-mode=ACCESSED_AND_THROTTLED_KEYS ``` 1. Switch from *accessed and throttled keys* mode to *throttled keys* mode. ``` aws dynamodb update-contributor-insights \ --table-name Music \ --contributor-insights-action=ENABLE \ --contributor-insights-mode=THROTTLED_KEYS ``` 1. Check the status during the transition. ``` aws dynamodb describe-contributor-insights --table-name Music ``` During the mode switch, the `ContributorInsightsStatus` will show as `ENABLING`. Once complete, it will show as `ENABLED` with the new mode. ### Managing Contributor Insights **To manage Contributor Insights settings** 1. Disable CloudWatch Contributor Insights for DynamoDB on the `AlbumTitle-index` global secondary index. ``` aws dynamodb update-contributor-insights \ --table-name Music --index-name AlbumTitle-index \ --contributor-insights-action=DISABLE ``` 1. List all Contributor Insights configurations in your account. ``` aws dynamodb list-contributor-insights ``` This shows all tables and indexes with Contributor Insights enabled, along with their modes. 1. Get detailed information about a specific configuration. ``` aws dynamodb describe-contributor-insights \ --table-name Music \ --index-name AlbumTitle-index ``` ### Example responses Here are example responses showing the differences between modes: #### Accessed and throttled keys mode response ``` { "TableName": "Music", "ContributorInsightsRuleList": [ "DynamoDBContributorInsights-PKC-Music-1234567890123", "DynamoDBContributorInsights-PKT-Music-1234567890123", "DynamoDBContributorInsights-SKC-Music-1234567890123", "DynamoDBContributorInsights-SKT-Music-1234567890123" ], "ContributorInsightsStatus": "ENABLED", "ContributorInsightsMode": "ACCESSED_AND_THROTTLED_KEYS", "LastUpdateDateTime": "2024-01-15T10:30:00.000Z" } ``` #### Throttled keys mode response ``` { "TableName": "Music", "ContributorInsightsRuleList": [ "DynamoDBContributorInsights-PKT-Music-1234567890123", "DynamoDBContributorInsights-SKT-Music-1234567890123" ], "ContributorInsightsStatus": "ENABLED", "ContributorInsightsMode": "THROTTLED_KEYS", "LastUpdateDateTime": "2024-01-15T10:35:00.000Z" } ``` Notice that throttled keys mode has fewer rules (only PKT and SKT), which corresponds to a more focused monitoring. # Using IAM with CloudWatch contributor insights for DynamoDB Using IAM The first time that you enable Amazon CloudWatch Contributor Insights for Amazon DynamoDB, DynamoDB automatically creates an AWS Identity and Access Management (IAM) service-linked role for you. This role, `AWSServiceRoleForDynamoDBCloudWatchContributorInsights`, allows DynamoDB to manage CloudWatch Contributor Insights rules on your behalf. Don't delete this service-linked role. If you delete it, all your managed rules will no longer be cleaned up when you delete your table or global secondary index. For more information about service-linked roles, see [Using service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) in the *IAM User Guide*. The following permissions are required: + To enable or disable CloudWatch Contributor Insights for DynamoDB, you must have `dynamodb:UpdateContributorInsights` permission on the table or index. + To view CloudWatch Contributor Insights for DynamoDB graphs, you must have `cloudwatch:GetInsightRuleReport` permission. + To describe CloudWatch Contributor Insights for DynamoDB for a given DynamoDB table or index, you must have `dynamodb:DescribeContributorInsights` permission. + To list CloudWatch Contributor Insights for DynamoDB statuses for each table and global secondary index, you must have `dynamodb:ListContributorInsights` permission. ## Example: Enable or disable CloudWatch contributor insights for DynamoDB The following IAM policy grants permissions to enable or disable CloudWatch Contributor Insights for DynamoDB. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:CreateServiceLinkedRole", "Resource": "arn:aws:iam::*:role/aws-service-role/contributorinsights.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBCloudWatchContributorInsights", "Condition": {"StringLike": {"iam:AWSServiceName": "contributorinsights.dynamodb.amazonaws.com"}} }, { "Effect": "Allow", "Action": [ "dynamodb:UpdateContributorInsights" ], "Resource": "arn:aws:dynamodb:*:*:table/*" } ] } ``` ------ For tables encryped by KMS key, the user needs to have kms:Decrypt permissions in order to update Contributor Insights. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:CreateServiceLinkedRole", "Resource": "arn:aws:iam::*:role/aws-service-role/contributorinsights.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBCloudWatchContributorInsights", "Condition": { "StringLike": { "iam:AWSServiceName": "contributorinsights.dynamodb.amazonaws.com" } } }, { "Effect": "Allow", "Action": [ "dynamodb:UpdateContributorInsights" ], "Resource": "arn:aws:dynamodb:*:*:table/*" }, { "Effect": "Allow", "Resource": "arn:aws:kms:*:*:key/*", "Action": [ "kms:Decrypt" ] } ] } ``` ------ ## Example: Retrieve CloudWatch contributor insights rule report The following IAM policy grants permissions to retrieve CloudWatch Contributor Insights rule report. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudwatch:GetInsightRuleReport" ], "Resource": "arn:aws:cloudwatch:*:*:insight-rule/DynamoDBContributorInsights*" } ] } ``` ------ ## Example: Selectively apply CloudWatch contributor insights for DynamoDB permissions based on resource The following IAM policy grants permissions to allow the `ListContributorInsights` and `DescribeContributorInsights` actions and denies the `UpdateContributorInsights` action for a specific global secondary index. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "dynamodb:ListContributorInsights", "dynamodb:DescribeContributorInsights" ], "Resource": "*" }, { "Effect": "Deny", "Action": [ "dynamodb:UpdateContributorInsights" ], "Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Books/index/Author-index" } ] } ``` ------ ## Using service-linked roles for CloudWatch Contributor Insights for DynamoDB Using service-linked roles CloudWatch Contributor Insights for DynamoDB uses AWS Identity and Access Management (IAM)[ service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). A service-linked role is a unique type of IAM role that is linked directly to CloudWatch Contributor Insights for DynamoDB. Service-linked roles are predefined by CloudWatch Contributor Insights for DynamoDB and include all the permissions that the service requires to call other AWS services on your behalf. A service-linked role makes setting up CloudWatch Contributor Insights for DynamoDB easier because you don’t have to manually add the necessary permissions. CloudWatch Contributor Insights for DynamoDB defines the permissions of its service-linked roles, and unless defined otherwise, only CloudWatch Contributor Insights for DynamoDB can assume its roles. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity. For information about other services that support service-linked roles, see [AWS Services That Work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) and look for the services that have **Yes** in the **Service-Linked Role** column. Choose a **Yes** with a link to view the service-linked role documentation for that service. ### Service-linked role permissions for CloudWatch Contributor Insights for DynamoDB CloudWatch Contributor Insights for DynamoDB uses the service-linked role named **AWSServiceRoleForDynamoDBCloudWatchContributorInsights**. The purpose of the service-linked role is to allow Amazon DynamoDB to manage Amazon CloudWatch Contributor Insights rules created for DynamoDB tables and global secondary indexes, on your behalf. The `AWSServiceRoleForDynamoDBCloudWatchContributorInsights` service-linked role trusts the following services to assume the role: + `contributorinsights.dynamodb.amazonaws.com ` The role permissions policy allows CloudWatch Contributor Insights for DynamoDB to complete the following actions on the specified resources: + Action: `Create and manage Insight Rules` on `DynamoDBContributorInsights` You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role. For more information, see [Service-Linked Role Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions) in the *IAM User Guide*. ### Creating a service-linked role for CloudWatch Contributor Insights for DynamoDB You don't need to manually create a service-linked role. When you enable Contributor Insights in the AWS Management Console, the AWS CLI, or the AWS API, CloudWatch Contributor Insights for DynamoDB creates the service-linked role for you. If you delete this service-linked role, and then need to create it again, you can use the same process to recreate the role in your account. When you enable Contributor Insights, CloudWatch Contributor Insights for DynamoDB creates the service-linked role for you again. ### Editing a service-linked role for CloudWatch Contributor Insights for DynamoDB CloudWatch Contributor Insights for DynamoDB does not allow you to edit the `AWSServiceRoleForDynamoDBCloudWatchContributorInsights` service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Editing a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) in the *IAM User Guide*. ### Deleting a service-linked role for CloudWatch Contributor Insights for DynamoDB You don't need to manually delete the `AWSServiceRoleForDynamoDBCloudWatchContributorInsights` role. When you disable Contributor Insights in the AWS Management Console, the AWS CLI, or the AWS API, CloudWatch Contributor Insights for DynamoDB cleans up the resources. You can also use the IAM console, the AWS CLI or the AWS API to manually delete the service-linked role. To do this, you must first manually clean up the resources for your service-linked role and then you can manually delete it. **Note** If the CloudWatch Contributor Insights for DynamoDB service is using the role when you try to delete the resources, then the deletion might fail. If that happens, wait for a few minutes and try the operation again. **To manually delete the service-linked role using IAM** Use the IAM console, the AWS CLI, or the AWS API to delete the `AWSServiceRoleForDynamoDBCloudWatchContributorInsights` service-linked role. For more information, see [Deleting a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role) in the *IAM User Guide*.