Contact Flow Log Analysis with AWS CloudWatch Insights
So, you have your Amazon Connect Contact Center setup and live. With the Real-Time and Historical Reports available in the Connect Console, you\u2019re able to see all the calls coming and going, which queues are full or empty, and which agents are busy or available. Here we can understand your caller's experience once they have left your IVR and are either waiting or dealing with an Agent. But what about their experience within the IVR itself? How often are they following a particular menu option? How often are they experiencing system errors caused by Lambda functions? What about their interactions with Lex Bots? Or entering information with their keypad?
Accessing AWS CloudWatch Insights
Your Amazon Connect instance can provide you with the data in Amazon CloudWatch in the form of Contact Flow Logs. You can use Contact Flow Logs (CFLs) to analyze your log data and the caller\u2019s experience in your IVR since each block in your Contact Flow is being processed and logged, both with log field input parameters and process results. These Amazon CloudWatch Logs can then be viewed in the CloudWatch Console by selecting Logs, then Log Group for your Connect Instance.
The more volume your Contact Center handles, however, the more difficult it will be too look through the standard log data in Amazon CloudWatch Log Streams. The CloudWatch console organizes and discovers field entries by timestamp, which means that concurrent calls will be all mixed together. While there is some filtering you can do with the log streams, there is a great tool available to us that does a good job at searching and analyzing CFLs using a \u201cpurpose-built query language.
From the CloudWatch Console, you can access the AWS CloudWatch Insights service which provides an interface where you can select one or more Log Groups to search through. Queries can be added to a CloudWatch Dashboard and Query results can be exported to CSV files. With this, we can easily search through CFLs regardless of call volume and within any time periods we desire.
Enabling Contact Flow Logs
We should note that Contact Flow Logs are not enabled by default. You must first navigate to your instance in the AWS console, and click “Contact Flows” on the left-hand side.
At the bottom, you will see a checkbox to “Enable Contact flow logs.”
Check this box, click “Apply” and note the destination Log Group for your logs.
Logging Contact Flow Data
Also, Contact Flows do not log data by default. For each Contact Flow, you must add the “Set Logging Behavior” block and ensure the value is enabled.
There are some situations in which you may not want logging enabled, such as a caller entering personal information, so you must be careful when enabling and disabling logging. This data will be accessible to anyone with CloudWatch dashboard access unless certain IAM permissions are set.[CA1] Check out [CA2] https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/iam-identity-based-access-control-cw.html to learn more about CloudWatch Console access.
A Quick Look at AWS CloudWatch Insights
Here is the CloudWatch Insights page inside your Amazon VPC (Virtual Private Cloud), which can be found under Logs on the left-hand side menu on the CloudWatch Console home page.
The top drop-down is where you will select the log group(s) you want to query. For Contact Flow Logs, you’ll choose your Connect Instance, which will have the following format: “/aws/connect/{instance-name}.” To the right of the log group selection, you will want to specify the date range in which you want to query. Like with most AWS services, you can select a variety of periods from 5 minutes to 4 weeks or any custom time frame. Help is also available on the far right of the console.
Below the Log Group, you will see the Query Editor.
This is where you will be able to enter your query to interactively search and analyze your CFLs. The editor provides some helpful code completion. When your query is ready, just hit the “Run query” button and wait. Depending on the time frame you specified, it may take a few moments to run. The more data that needs to be scanned, the longer the time it takes. If there is any problem with your query, the editor will let you know before it starts to execute the query.
The results will be populated in the box below the timeline. The timeline can give you a quick visual indication of how many log messages your query returned in your selected timeframe. You can also see exactly how many records were returned along with how much data was scanned and the scanning speed below the timeline.
Once you have your results, you can freely expand the logs as needed to get further details and look at the results directly.
You may also click the “Actions” button to reveal several export options if you want to pull this data into a different program. You can also add your query to a CloudWatch Dashboard in order to keep everything together in the same place.
Amazon CloudWatch Logs by CFL Type
Let’s first look at the structure of CFL. The following is a real example but with a few details redacted.
There are five standard attributes for all CFLs which I have listed below. The timestamps are in UNIX format and CloudWatch Insights has helper functions to translate to friendlier formats if needed.
- @ingestionTime is the timestamp the log was actually received and consumed into CloudWatch.
- @log is the name of the Log Group.
- @logStream contains the Log Stream name for that specific period of time.
- @message contains the unparsed JSON log data.
- @timestamp contains the event timestamp for when the log was added to CloudWatch.
Below these standard attributes, you can see that the JSON data contained in the @message is broken out into easily read and searchable fields using a parse message.
Basic Contact Flow Log Queries
The sample queries below help address common scenarios in CFL analysis. Once you get the hang of the commands and syntax, you’ll be writing your own queries with no effort!
Default Query
This query is the default, which appears when you first load the Log Group. It shows the logs in descending order and limited to the last 20 log messages. We’ll use this as a starting point for the following queries but remove the limit keyword. Note that all the syntax commands start with the “|” (UNIX-style pipe character) at the beginning of the line; this is required. You may also write comments by using “#” at the beginning of the line, which will be ignored by your query.
Get All CFL’s for specific Contact Id
This query will retrieve all CFL’s for the specified Contact Id displayed in order by timestamp. This is the entire journey of the caller through your Contact Flows up until they are connected to an Agent.
Count Unique Calls
This query will return the number of any call which generated some type of logging. This will not necessarily return the number of calls to your Connect Instance, only those where logging is enabled.
Find Lambda Errors
This query will return all logs where a Lambda Function Module returned an error. This will help you identify why a Lambda failed by returning the list of parameters sent. You can see if it was an isolated incident or a general trend under certain conditions. The full error message is “The Lambda Function Returned An Error.”
Find all Specific Lambda Invocations
This query will return all logs for a specific Lambda Function. You can see the Parameters sent to the Lambda Function and the Returned Results for each invocation logged.
Find all Lambda Invocations with Specific Parameter Value
This query will return all logs for the specified Lambda Function where the Parameter is equal to a certain value. In this sample query, the Parameter key is “Group” and the value is “Sales.”
Count Unique Calls hitting Certain Call Flow
This query will return the total number of unique calls that journeyed through the specified Contact Flow. This is useful if you want to determine the percentage of callers that go to a certain Contact Flow based on Menu Options, for example.
Count how many times a user pressed an option in a Get User Input Block
This query will return the number of times a specific option was selected on a Get User Input Block. In this sample query, we want to know how many callers selected option 2. Get the total number for all other options to compare which option is most popular. Also, you can swap out “GetUserInput” with “StoreUserInput” since those blocks work in similar way.
Count how many times an attribute was set
This query will return the number of times a specific Contact Attribute was set. In this sample query, we want to know how many times callers wanted to check their current account balance in a self-service Contact Flow rather than be directed to an agent.
Contact Flow Module Types
Here is a handy reference for Contact Flow Module Types with their respective Connect Blocks. Most are obvious but there are a few differences between some of them. Note that, for example, the SetContactFlow and Transfer module types are used by several different Connect Blocks and actual type is passed a Parameter to the module, available in the CFL details. When searching for a specific Connect block in your CFLs, use the specified ContactFlowModuleType.
Conclusion
I hope with this information you can start using AWS CloudWatch Insights to quickly and interactively search and analyze your Contact Center experience. Amazon CloudWatch Logs Insights enable you to get valuable information about how your IVR’s are being used by callers and pinpoint any errors or issues that they might be encountering, just by learning a few commands. This service is a must for Contact Flow development and troubleshooting.
For more information regarding CloudWatch Insights, check out the great documentation at https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html. There you can learn more about the commands and sample queries used throughout this post and additional operators and helper functions available.
Please note that AWS CloudWatch Insights is not a free service, it costs $0.005 per GB of data scanned. For more information, check out https://aws.amazon.com/cloudwatch/pricing/.