Monitor Amazon Connect API usage using Amazon CloudWatch alarms

Many organizations utilize Amazon Connect to run their contact centers and integrate custom applications through Connect APIs. These APIs are used to streamline and customize various aspects of contact center operations, such as managing agent states, retrieving real-time metrics, automating contact center processes, and customizing the overall customer experience to meet specific business requirements. However, in times of high call volumes, these API integrations may generate significant number of requests. When API usage exceeds the provisioned capacity, customer requests are throttled impacting the performance of the contact center.

In this blog post, we’ll explore how customers can utilize Amazon CloudWatch to actively monitor Amazon Connect contact center API usage and receive alerts when the usage approaches defined capacity limits. This allows them to proactively take actions like optimizing applications or adding capacity before encountering performance issues. The process is streamlined through the AWS Cloud Development Kit (CDK), which enables customers to create and manage CloudWatch alarms programmatically. By setting up comprehensive monitoring and alerting for Amazon Connect API usage, businesses can ensure their contact center operations run smoothly and efficiently at all times, staying ahead of potential bottlenecks and maintaining optimal performance.

Solution Overview

The solution will walk you through the process of creating an Amazon CloudWatch alarm to monitor one of the Amazon Connect APIs called DescribeQueue. We will explore three different ways to create the alarm and you can use one of them for your use case deployment.

1. Creating the alarm from Amazon CloudWatch
2. Creating the alarm from Service Quotas
3. Creating the alarm using AWS Cloud Development Kit (CDK)

Prerequisites

For this walkthrough, it is assumed that you understand and have access to the following resources:

• An AWS account
• An Amazon Connect instance
• An AWS CDK installation
• An Amazon SNS topic

Deploying the solution

To demonstrate the process of creating an alarm to monitor Amazon Connect APIs, we will first create CloudWatch metric math function to display the current usage of DescribeQueue API as a percentage of the SERVICE QUOTA. You can choose any other API that you wish to create alarm for. If you do not see the API or its metrics, it means the API has not been invoked. To generate metrics for DescribeQueue API, login to your Amazon Connect instance, choose Queues under Routing and click on BasicQueue or any other queue.

A) Steps to create the alarm from Amazon CloudWatch console

1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
2. In the navigation pane on the left-hand side, choose Metrics.
3. Click on All metrics, choose Usage and then choose By AWS Resource. The list of service quota usage metrics appears.
4. Enter the API Name DescribeQueue in the search box and select the check box. You can also type the service name Connect and select the API from the resultant list. The graph displays your current usage of the API.
5. To see your current usage as a percentage of the quota, do the following
   1. Choose the Graphed metrics tab.
   2. Click on Add math dropdown and choose Start with empty expression. In the new row, under Details, enter m1/SERVICE_QUOTA(m1)*100 and click on Apply.
6. To set an alarm that notifies you if you approach the service quota, do the following:
   1. On the row with m1/SERVICE_QUOTA(m1)*100, under Actions, choose the alarm icon. It looks like a bell. The alarm creation page appears.
   2. Select Period as 1 minute or 5 minutes.
   3. Under Conditions, ensure that Threshold type is Static and Whenever Expression1 is is set to Greater/Equal. Under than, enter 80. This creates an alarm that goes into ALARM state when your usage is or exceeds 80 percent of the quota.
   4. Under Additional configuration, specify Datapoints to alarm as 3 out of 3 or as per your requirement and select Treat missing data as missing for Missing data treatment and choose Next.
   5. On the next page, under Notification, ensure In alarm is selected for Alarm state trigger and choose Select an existing SNS topic followed by selecting the SNS topic under Send a notification to or Create a new topic followed by entering a unique topic name and providing email endpoints that will receive the notification. You can also choose Use topic ARN to notify other accounts and then choose Next. The topic you select is notified when the alarm goes to ALARM state.
   6. On the next page, enter Alarm name as DescribeQueueAlarm and then choose Next.
   7. Choose Create alarm.

B) Steps to create the alarm from Service Quota

Alternatively, you can also create this alarm from Service Quotas.

1. Visit the Service Quotas console at https://console.aws.amazon.com/servicequotas/.
2. In the navigation pane on the left-hand side, choose AWS services.
3. Search for Amazon Connect in the list of services and select it.
4. Under Service quotas search for DescribeQueue. The quota name will be listed as Rate of DescribeQueue API requests. Click on it to see the details and the different tabs underneath it.
5. Choose the Alarms tab and click on Create.
6. Select Alarm threshold as 80% of the applied quota value
7. Enter Alarm name as DescribeQueueAlarm and click on Create.
8. To edit the alarm, click on the DescribeQueueAlarm name to view the alarm page and choose Edit under Actions. Here you can update the period, datapoints to alarm and select an Amazon SNS topic or create a new one.

C) Steps to create the alarm using AWS CDK

For customers who would like to automate the process of creating the CloudWatch Alarm to monitor Amazon Connect APIs, can use AWS Cloud Development Kit (CDK). We will work with AWS CDK in Python to setup the Amazon CloudWatch alarm.

1. Create the app

$ mkdir DescribeQueueAlarm
$ cd DescribeQueueAlarm

2. Initialize the app

cdk init app --language python

3. Activate the app’s Python virtual environment and install the AWS CDK core dependencies

source .venv/bin/activate
python -m pip install -r requirements.txt

4. Use the following example to add an Amazon CloudWatch alarm. Replace the sample SNS topic with the one you created as a prerequisite
   In describe_queue_alarm/describe_queue_alarm_stack.py

from aws_cdk import (
    Stack,
)
from constructs import Construct
from aws_cdk import aws_cloudwatch as cloudwatch

class DescribeQueueAlarmStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)
        
        cfn_alarm = cloudwatch.CfnAlarm(self, "DescribeQueueAlarm",
            alarm_name="DescribeQueueAlarm",
            alarm_description="Alarm to monitor Describe Queue API Usage",
            comparison_operator="GreaterThanOrEqualToThreshold",
            evaluation_periods=3,
            datapoints_to_alarm=3,
            metrics=[cloudwatch.CfnAlarm.MetricDataQueryProperty(
                id="m1",
                label="Describe Queue",
                metric_stat=cloudwatch.CfnAlarm.MetricStatProperty(
                    metric=cloudwatch.CfnAlarm.MetricProperty(
                        namespace="AWS/Usage",
                        metric_name="CallCount",
                        dimensions=[cloudwatch.CfnAlarm.DimensionProperty(
                            name="Resource",
                            value="DescribeQueue"
                        ),
                        cloudwatch.CfnAlarm.DimensionProperty(
                        name="Service",
                        value="Connect"
                        ),
                        cloudwatch.CfnAlarm.DimensionProperty(
                        name="Type",
                        value="API"
                        ),
                        cloudwatch.CfnAlarm.DimensionProperty(
                        name="Class",
                        value="None"
                    )]
                    ),
                    period=60,
                    stat="Average"
                ),
                return_data=False),
            cloudwatch.CfnAlarm.MetricDataQueryProperty(
                id="e1",
                expression="(m1/SERVICE_QUOTA(m1))*100",
                label="describe_queue_pct_utilisation",
                return_data=True
            )],
            threshold=80,
            treat_missing_data="missing",
            #Replace SNS topic with the one you created as prerequisite
            alarm_actions=['arn:aws:sns:us-east-1:1234567890:SnsTopic']
        )  

5. Synthesize an AWS CloudFormation template

cdk synth

6. Deploy your CDK stack to AWS CloudFormation

cdk deploy

Cleanup

To delete the CloudWatch alarm:

1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
2. In the navigation pane on the left-hand side, choose All alarms.
3. Select DescribeQueueAlarm from the list of alarms.
4. Under Actions, choose Delete to delete the alarm.

If you have created a SNS topic, follow the below steps to delete the same:

1. Open the SNS console at https://console.aws.amazon.com/sns/home.
2. In the left navigation pane, choose Topics.
3. On the Topics page, select the topic you used during CloudWatch alarm creation, and then choose Delete.
4. In the Delete topic dialog box, enter delete me, and then choose Delete.

To delete the alarm created from Service Quotas, follow the same steps as above. If you have used AWS CDK to create the CloudWatch alarm, you can delete the AWS CloudFormation stack and all resources associated with it using the below command

cdk destroy

Conclusion

In this blog, we discussed how you can monitor Amazon Connect API usage using Amazon CloudWatch alarms and get notified via Amazon Simple Notification Service when the usage breaches the threshold. We also looked at how you can use AWS Cloud Development Kit (CDK) to automate the process of creating Amazon CloudWatch Alarm to monitor API usage.

To learn more about the list of services that report API usage metrics to CloudWatch, you can read AWS API usage metrics.

About the Author

Naseer Sayyad is a Senior Technical Account Manager at Amazon Web Services. Naseer partners with AWS enterprise customers and helps them to be successful in their cloud transformation journey. He is passionate about cloud computing and automation. Outside work, he enjoys travel and photography. You can reach him on LinkedIn @naseersayyad